编写第一个 Flutter 应用

第一步：创建初始化工程
Step 1: Create the starter Flutter app
第二步：使用外部 package
Step 2: Use an external package
第三步：添加一个 Stateful widget
Step 3: Add a Stateful widget
第四步：创建一个无限滚动的 ListView
Step 4: Create an infinite scrolling ListView
以 profile 模式运行
Profile or release runs

If you prefer an instructor-led version of this codelab, check out the following workshop:

The app that you'll be building

这是一个指引你完成第一个 Flutter 应用的手把手操作教程（我们也称之为是 codelab）。我们将会着手创建一个简单的 Flutter 应用，无需 Dart 语言、移动开发语言或 Web 开发经验，只需你具备面向对象语言开发基础即可（如变量，循环和条件语句）。

This is a guide to creating your first Flutter app. If you are familiar with object-oriented code and basic programming concepts such as variables, loops, and conditionals, you can complete this tutorial. You don’t need previous experience with Dart, mobile, or web programming.

完整的教程分为两部分，本页面是第一部分的内容，你可以在这里查看第二部分的内容。 (Codelabs 里的第一部分内容与本页内容相同)。

This codelab is part 1 of a two-part codelab. You can find part 2 on Google Developers Codelabs (as well as a copy of this codelab, part 1).

第一部分的内容概览

What you’ll build in part 1

你将完成一个简单的应用，功能是：为一个创业公司生成建议的公司名称。用户可以选择和取消选择的名称、保存喜欢的名称。该代码一次生成十个名称，当用户滚动时，会生成新一批名称。

You’ll implement a simple app that generates proposed names for a startup company. The user can select and unselect names, saving the best ones. The code lazily generates 10 names at a time. As the user scrolls, more names are generated. There is no limit to how far a user can scroll.

页面上方的这个 GIF 可以引导你预览本 codelab 做完之后的应用效果图。

The animated GIF shows how the app works at the completion of part 1.

第一部分，我们将共同构建：

What you’ll learn in part 1

Flutter 如何在 Android、iOS 和 Web 里自动适应不同的 UI 体系
How to write a Flutter app that looks natural on iOS, Android, and the web
Flutter 工程/项目的基本结构
Basic structure of a Flutter app
查找和使用 packages 来扩展功能
Finding and using packages to extend functionality
使用热重载 (hot reload) 加快开发周期
Using hot reload for a quicker development cycle
如何实现有状态的 widget
How to implement a stateful widget
如何创建一个无限的、延迟加载的列表
How to create an infinite, lazily loaded list

在本 codelab 的第二部分，你还将学到添加交互，修改应用的主题，以及为应用添加一个新的页面（在 Flutter，我们称之为 route）。

In part 2 of this codelab, you’ll add interactivity, modify the app’s theme, and add the ability to navigate to a new screen (called a route in Flutter).

所需工具

What you'll use

你需要安装两部分内容来完成本次实验： Flutter SDK 安装和编辑器 (editor) 设置。本 codelab 里，我们以 macOS 环境下的 Android Studio 以做演示，但你可以选用更顺手的配置。

You need two pieces of software to complete this lab: the Flutter SDK and an editor. This codelab assumes Android Studio, but you can use your preferred editor.

你可以通过如下任何设备完成本 codelab：

You can run this codelab by using any of the following devices:

开启开发者模式 (developer mode) 的 Android 和 / 或 iOS 真机；
A physical device (Android or iOS) connected to your computer and set to developer mode
iOS 模拟器 (需要安装 Xcode 工具)；
The iOS simulator (requires installing Xcode tools)
Android 模拟器 (需要安装设置 Android Studio)。
The Android emulator (requires setup in Android Studio)
浏览器（如果需要 debug，则需要用 Chrome 浏览器）
A browser (Chrome is required for debugging)

任何一个 Flutter 的项目都可以编译为 web 应用。你可以在 IDE 中打开 devices 选择器，或者是在命令行中输入 flutter devices，这样你就可以看到 Chrome 以及 Web server 选项卡。 Chrome 设备将会自动打开 Chrome。 Web server 则会运行一个服务程式托管应用，这样你就可以在任意浏览器加载它。在开发时请使用 Chrome 进行调试，以使用 DevTools。当你想在其他浏览器测试时，请使用 web server。更多详细信息请查看使用 Flutter 构建 web 应用，以及编写你的第一个 Flutter web 应用程序。

Every Flutter app you create also compiles for the web. In your IDE under the devices pulldown, or at the command line using flutter devices, you should now see Chrome and Web server listed. The Chrome device automatically starts Chrome. The Web server starts a server that hosts the app so that you can load it from any browser. Use the Chrome device during development so that you can use DevTools, and the web server when you want to test on other browsers. For more information, see Building a web application with Flutter and Write your first Flutter app on the web.

第一步：创建初始化工程

Step 1: Create the starter Flutter app

按照这个指南中所描述的步骤，创建一个简单的、基于模板的 Flutter 工程，然后将项目命名为 startup_namer (而不是 myapp)，接下来你将会修改这个工程来完成最终的 App。

Create a simple, templated Flutter app, using the instructions in Getting Started with your first Flutter app. Name the project startup_namer (instead of flutter_app).

在这个示例中，你将主要编辑 Dart 代码所在的 lib/main.dart 文件,

You’ll mostly edit lib/main.dart, where the Dart code lives.

替换 lib/main.dart
删除 lib/main.dart 中的所有代码，然后替换为下面的代码，它将在屏幕的中心显示”Hello World”。
Replace the contents of lib/main.dart.
Delete all of the code from lib/main.dart. Replace with the following code, which displays “Hello World” in the center of the screen.
lib/main.dart
```
// Copyright 2018 The Flutter team. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
 @override
 Widget build(BuildContext context) {
 return MaterialApp(
 title: 'Welcome to Flutter',
 home: Scaffold(
 appBar: AppBar(
 title: const Text('Welcome to Flutter'),
 ),
 body: const Center(
 child: Text('Hello World'),
 ),
 ),
 );
 }
}
```
小提示

在向你的工程项目中粘贴代码的时候，缩进可能会变形。你可以使用下面的 Flutter 工具修复此问题：
When pasting code into your app, indentation can become skewed. You can fix this with the following Flutter tools:
- Android Studio 和 IntelliJ IDEA: 右键单击Dart代码，然后选择 Reformat Code with dartfmt
 Android Studio and IntelliJ IDEA: Right-click the code and select Reformat Code with dartfmt.
- VS Code: 右键单击并选择 Format Document.、
 VS Code: Right-click and select Format Document.
- Terminal: 运行 flutter format <filename>
 Terminal: Run flutter format <filename>.
运行你的工程项目，根据不同的操作系统，你会看到如下运行结果界面：
Run the app in the way your IDE describes. You should see either Android, iOS, or web output, depending on your device.

Android

iOS

小提示

第一次真机运行的时候可能会需要更多的等待时间，但是这是值得的，因为接下来你就可以使用热重载（hot reload）功能，真正的为下次运行时更新的预览节省更多时间。如果你是在终端窗口里通过 flutter run 运行应用的话，直接输入 r 进行热重载。
The first time you run on a physical device, it can take a while to load. Afterward, you can use hot reload for quick updates. Save also performs a hot reload if the app is running. When running an app directly from the console using flutter run, enter r to perform hot reload.

观察和分析

Observations

本示例创建了一个具有 Material Design 风格的应用， Material 是一种移动端和网页端通用的视觉设计语言， Flutter 提供了丰富的 Material 风格的 widgets。在 pubspec.yaml 文件的 flutter 部分选择加入 uses-material-design: true 会是一个明智之举，通过这个可以让您使用更多 Material 的特性，比如其预定义好的图标集。
This example creates a Material app. Material is a visual design language that is standard on mobile and the web. Flutter offers a rich set of Material widgets.
It’s a good idea to have a uses-material-design: true entry in the flutter section of your pubspec.yaml file. This will allow you to use more features of Material, such as their set of predefined Icons.
主函数（main）使用了 (=>) 符号，这是 Dart 中单行函数或方法的简写。
The main() method uses arrow (=>) notation. Use arrow notation for one-line functions or methods.
该应用程序继承了 StatelessWidget，这将会使应用本身也成为一个 widget。在 Flutter 中，几乎所有都是 widget，包括对齐 (alignment)、填充 (padding) 和布局 (layout)。
The app extends StatelessWidget, which makes the app itself a widget. In Flutter, almost everything is a widget, including alignment, padding, and layout.
Scaffold 是 Material 库中提供的一个 widget，它提供了默认的导航栏、标题和包含主屏幕 widget 树的 body 属性。 widget 树可以很复杂。
The Scaffold widget, from the Material library, provides a default app bar, and a body property that holds the widget tree for the home screen. The widget subtree can be quite complex.
一个 widget 的主要工作是提供一个 build() 方法来描述如何根据其他较低级别的 widgets 来显示自己。
A widget’s main job is to provide a build() method that describes how to display the widget in terms of other, lower level widgets.
本示例中的 body 的 widget 树中包含了一个 Center widget， Center widget 又包含一个 Text 子 widget， Center widget 可以将其子 widget 树对齐到屏幕中心。
The body for this example consists of a Center widget containing a Text child widget. The Center widget aligns its widget subtree to the center of the screen.

第二步：使用外部 package

Step 2: Use an external package

在这一步中，你将开始使用一个名为 english_words 的开源软件包，其中包含数千个最常用的英文单词以及一些实用功能。

In this step, you’ll start using an open-source package named english_words, which contains a few thousand of the most used English words plus some utility functions.

你可以在 pub.dev 上找到 english_words 软件包以及其他许多开源软件包。

You can find the english_words package, as well as many other open source packages, on pub.dev.

pubspec.yaml 文件管理 Flutter 应用程序的 assets（资源，如图片、package等）。在pubspec.yaml 中，将 english_words（3.1.5 或更高版本）添加到依赖项列表，如下面高亮显示的行：
The pubspec.yaml file manages the assets and dependencies for a Flutter app. In pubspec.yaml, add english_words (3.1.5 or higher) to the dependencies list:

{step1_base → step2_use_package}/pubspec.yaml Viewed

@@ -9,4 +9,5 @@

9

9

dependencies:

10

10

flutter:

11

11

sdk: flutter

12

12

cupertino_icons: ^1.0.2

13

+ english_words: ^4.0.0
在 Android Studio 的编辑器视图中查看 pubspec.yaml 文件时，点击 Pub get 会将依赖包安装到你的项目。你应该会在控制台中看到以下内容：
While viewing the pubspec.yaml file in Android Studio’s editor view, click Pub get. This pulls the package into your project. You should see the following in the console:
```
$ flutter pub get
Running "flutter pub get" in startup_namer...
Process finished with exit code 0
```
在执行 Pub get 命令时会自动生成一个名为 pubspec.lock 文件，这里包含了你依赖 packages 的名称和版本。
Performing Pub get also auto-generates the pubspec.lock file with a list of all packages pulled into the project and their version numbers.
在 lib/main.dart 中引入，如下所示：
In lib/main.dart, import the new package:
lib/main.dart
```
import 'package:english_words/english_words.dart';
import 'package:flutter/material.dart';
```
在你输入时，Android Studio会为你提供有关库导入的建议。然后它将呈现灰色的导入字符串，让你知道导入的库截至目前尚未被使用。
As you type, Android Studio gives you suggestions for libraries to import. It then renders the import string in gray, letting you know that the imported library is unused (so far).

接下来，我们使用 English words 包生成文本来替换字符串”Hello World”：

Use the English words package to generate the text instead of using the string “Hello World”:

{step1_base → step2_use_package}/lib/main.dart Viewed

@@ -9,14 +10,15 @@
 class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
+    final wordPair = WordPair.random();
     return MaterialApp(
       title: 'Welcome to Flutter',
       home: Scaffold(
         appBar: AppBar(
           title: const Text('Welcome to Flutter'),
         ),
-        body: const Center(
-          child: Text('Hello World'),
+        body: Center(
+          child: Text(wordPair.asPascalCase),
         ),
       ),
     );

如果应用程序正在运行，请使用热重载按钮更新正在运行的应用程序。每次单击热重载或保存项目时，都会在正在运行的应用程序中随机选择不同的单词对。这是因为单词对是在 build 方法内部生成的。每次 MaterialApp 需要渲染时或者在 Flutter Inspector 中切换平台时 build 都会运行。
If the app is running, hot reload to update the running app. Each time you click hot reload, or save the project, you should see a different word pair, chosen at random, in the running app. This is because the word pairing is generated inside the build method, which is run each time the MaterialApp requires rendering, or when toggling the Platform in Flutter Inspector.

Android

iOS

遇到问题?

Problems?

如果你的应用程序运行不正常，请查找是否有拼写错误。如果需要通过 Flutter 的 debug 工具，可以查看开发者工具页面来查看 debug 和 profile 的工具。如果需要，使用下面链接中的代码来对比更正。

If your app is not running correctly, look for typos. If you want to try some of Flutter’s debugging tools, check out the DevTools suite of debugging and profiling tools. If needed, use the code at the following links to get back on track.

Step 3: Add a Stateful widget

Stateless widgets 是不可变的，这意味着它们的属性不能改变 —— 所有的值都是 final。

Stateless widgets are immutable, meaning that their properties can’t change—all values are final.

Stateful widgets 持有的状态可能在 widget 生命周期中发生变化，实现一个 stateful widget 至少需要两个类： 1）一个 StatefulWidget 类；2）一个 State 类，StatefulWidget 类本身是不变的，但是 State 类在 widget 生命周期中始终存在。

Stateful widgets maintain state that might change during the lifetime of the widget. Implementing a stateful widget requires at least two classes: 1) a StatefulWidget class that creates an instance of 2) a State class. The StatefulWidget class is, itself, immutable and can be thrown away and regenerated, but the State class persists over the lifetime of the widget.

在这一步，你将添加一个 stateful widget（有状态的 widget）—— RandomWords，它会创建自己的状态类 —— _RandomWordsState，然后你需要将 RandomWords 内嵌到已有的无状态的 MyApp widget。

In this step, you’ll add a stateful widget, RandomWords, which creates its State class, _RandomWordsState. You’ll then use RandomWords as a child inside the existing MyApp stateless widget.

创建有状态 widget 的样板代码。
在 lib/main.dart 中，将光标置于所有代码之后，输入回车几次另起新行。在 IDE 中，输入 stful，编辑器就会提示您是否要创建一个 Stateful widget。按回车键表示接受建议，随后就会出现两个类的样板代码，光标也会被定位在输入有状态 widget 的名称处。
Create the boilerplate code for a stateful widget.
In lib/main.dart, position your cursor after all of the code, enter Return a couple times to start on a fresh line. In your IDE, start typing stful. The editor asks if you want to create a Stateful widget. Press Return to accept. The boilerplate code for two classes appears, and the cursor is positioned for you to enter the name of your stateful widget.
输入 RandomWords 作为有状态 widget 的名称。
RandomWords widget 的主要作用就是创建其对应的 State 类。

输入 RandomWords 作为有有状态 widget 的名称后， IDE 会自动更新其对应的 State 类，并将其命名为 _RandomWordsState。默认情况下，State 类的名称带有下划线前缀。 Dart 语言中，给标识符加上下划线前缀可以增强隐私性，并且这也是针对 State 对象推荐的最佳实践写法。

IDE 也会自动将状态类继承自 State<RandomWords>，这表示专门用于 RandomWords 的通用 State 类。该应用程序的大多数逻辑都位于此处—它维护 RandomWords widget 的状态。该类会保存生成的单词对的列表，该列表随用户滚动而无限增长，在本实验的第 2 部分中，用户可以通过点击心形图标，添加或删除列表中收藏的单词对。

这两个类现在都如下所示：
Enter RandomWords as the name of your widget.
The RandomWords widget does little else beside creating its State class.

Once you’ve entered RandomWords as the name of the stateful widget, the IDE automatically updates the accompanying State class, naming it _RandomWordsState. By default, the name of the State class is prefixed with an underbar. Prefixing an identifier with an underscore enforces privacy in the Dart language and is a recommended best practice for State objects.

The IDE also automatically updates the state class to extend State<RandomWords>, indicating that you’re using a generic State class specialized for use with RandomWords. Most of the app’s logic resides here—it maintains the state for the RandomWords widget. This class saves the list of generated word pairs, which grows infinitely as the user scrolls and, in part 2 of this lab, favorites word pairs as the user adds or removes them from the list by toggling the heart icon.

Both classes now look as follows:
```
class RandomWords extends StatefulWidget {
 @override
 _RandomWordsState createState() => _RandomWordsState();
}

class _RandomWordsState extends State<RandomWords> {
 @override
 Widget build(BuildContext context) {
 return Container();
 }
}
```

更新 _RandomWordsState 中的 build() 方法：

Update the build() method in _RandomWordsState:

class _RandomWordsState extends State<RandomWords> {
    @override
    Widget build(BuildContext context) {
      final wordPair = WordPair.random();
      return Text(wordPair.asPascalCase);
    }
  }

通过以下差异所示的更改，删除 MyApp 中单词生成的代码：

Remove the word generation code from MyApp by making the changes shown in the following diff:

{step2_use_package → step3_stateful_widget}/lib/main.dart Viewed

@@ -10,7 +10,6 @@
 class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
-    final wordPair = WordPair.random();
     return MaterialApp(
       title: 'Welcome to Flutter',
       home: Scaffold(
@@ -18,8 +17,8 @@
           title: const Text('Welcome to Flutter'),
         ),
         body: Center(
-          child: Text(wordPair.asPascalCase),
+          child: RandomWords(),
         ),
       ),
     );
   }

重启应用。应用应该像之前一样运行，每次热重载或保存应用程序时都会显示一个单词对。
Restart the app. The app should behave as before, displaying a word pairing each time you hot reload or save the app.

遇到问题？

Problems?

lib/main.dart

第四步：创建一个无限滚动的 ListView

Step 4: Create an infinite scrolling ListView

在该步骤中，您会拓展 _RandomWordsState 以生成并显示单词对列表。随着用户滚动，列表（显示在 ListView widget 中）将无限增长。 ListView 的 builder 工厂构造函数使您可以按需延迟构建列表视图。

In this step, you’ll expand _RandomWordsState to generate and display a list of word pairings. As the user scrolls the list (displayed in a ListView widget) grows infinitely. ListView’s builder factory constructor allows you to build a list view lazily, on demand.

向 _RandomWordsState 类中添加一个 _suggestions 列表以保存建议的单词对，同时，添加一个 _biggerFont 变量来增大字体大小。
Add a _suggestions list to the _RandomWordsState class for saving suggested word pairings. Also, add a _biggerFont variable for making the font size larger.
lib/main.dart
```
class _RandomWordsState extends State<RandomWords> {
 final _suggestions = <WordPair>[];
 final _biggerFont = const TextStyle(fontSize: 18.0);
 // ···
}
```
接下来，我们将向 _RandomWordsState 类添加一个 _buildSuggestions() 方法，此方法构建显示建议单词对的 ListView。
Next, you’ll add a _buildSuggestions() function to the _RandomWordsState class. This method builds the ListView that displays the suggested word pairing.

ListView 类提供了一个名为 itemBuilder 的 builder 属性，这是一个工厂匿名回调函数，接受两个参数 BuildContext 和行迭代器 i。迭代器从 0 开始，每调用一次该函数 i 就会自增，每次建议的单词对都会让其递增两次，一次是 ListTile，另一次是 Divider。它用于创建一个在用户滚动时候无限增长的列表。
The ListView class provides a builder property, itemBuilder, that’s a factory builder and callback function specified as an anonymous function. Two parameters are passed to the function—the BuildContext, and the row iterator, i. The iterator begins at 0 and increments each time the function is called. It increments twice for every suggested word pairing: once for the ListTile, and once for the Divider. This model allows the suggested list to continue growing as the user scrolls.
向 _RandomWordsState 类添加 _buildSuggestions() 方法，内容如下：
Add a _buildSuggestions() function to the _RandomWordsState class:
lib/main.dart (_buildSuggestions)
```
Widget _buildSuggestions() {
  return ListView.builder(
      padding: const EdgeInsets.all(16.0),
      itemBuilder: /*1*/ (context, i) {
        if (i.isOdd) return const Divider(); /*2*/

        final index = i ~/ 2; /*3*/
        if (index >= _suggestions.length) {
          _suggestions.addAll(generateWordPairs().take(10)); /*4*/
        }
        return _buildRow(_suggestions[index]);
      });
}
```
1. 对于每个建议的单词对都会调用一次 itemBuilder，然后将单词对添加到 ListTile 行中。在偶数行，该函数会为单词对添加一个 ListTile row，在奇数行，该函数会添加一个分割线的 widget，来分隔相邻的词对。注意，在小屏幕上，分割线看起来可能比较吃力。
  The itemBuilder callback is called once per suggested word pairing, and places each suggestion into a ListTile row. For even rows, the function adds a ListTile row for the word pairing. For odd rows, the function adds a Divider widget to visually separate the entries. Note that the divider might be difficult to see on smaller devices.
2. 在 ListView 里的每一行之前，添加一个 1 像素高的分隔线 widget。
  Add a one-pixel-high divider widget before each row in the ListView.
3. 语法 i ~/ 2 表示 i 除以 2，但返回值是整型（向下取整），比如 i 为：1, 2, 3, 4, 5 时，结果为 0, 1, 1, 2, 2，这个可以计算出 ListView 中减去分隔线后的实际单词对数量。
  The expression i ~/ 2 divides i by 2 and returns an integer result. For example: 1, 2, 3, 4, 5 becomes 0, 1, 1, 2, 2. This calculates the actual number of word pairings in the ListView, minus the divider widgets.
4. 如果是建议列表中最后一个单词对，接着再生成 10 个单词对，然后添加到建议列表。
  If you’ve reached the end of the available word pairings, then generate 10 more and add them to the suggestions list.
对于每一个单词对，_buildSuggestions() 都会调用一次 _buildRow()。这个函数在 ListTile 中显示每个新词对，这使你在下一步中可以生成更漂亮的显示行，详见本 codelab 的第二部分。
The _buildSuggestions() function calls _buildRow() once per word pair. This function displays each new pair in a ListTile, which allows you to make the rows more attractive in the next step.

在 _RandomWordsState 中添加 _buildRow() 函数 :

Add a _buildRow() function to _RandomWordsState:

Widget _buildRow(WordPair pair) {
  return ListTile(
    title: Text(
      pair.asPascalCase,
      style: _biggerFont,
    ),
  );
}

更新 _RandomWordsState 的 build() 方法以使用 _buildSuggestions()，而不是直接调用单词生成库，代码更改后如下：（使用 Scaffold 类实现基础的 Material Design 布局）
In the _RandomWordsState class, update the build() method to use _buildSuggestions(), rather than directly calling the word generation library. (Scaffold implements the basic Material Design visual layout.) Replace the method body with the highlighted code:
lib/main.dart (build)
```
@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(
      title: const Text('Startup Name Generator'),
    ),
    body: _buildSuggestions(),
  );
}
```

更新 MyApp 的 build() 方法，修改 title 的值来改变标题，修改 home 的值为 RandomWords widget。

In the MyApp class, update the build() method by changing the title, and changing the home to be a RandomWords widget:

{step3_stateful_widget → step4_infinite_list}/lib/main.dart Viewed

@@ -10,15 +10,8 @@
 class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
-      title: 'Welcome to Flutter',
-      home: Scaffold(
-        appBar: AppBar(
-          title: const Text('Welcome to Flutter'),
-        ),
-        body: Center(
-          child: RandomWords(),
-        ),
-      ),
+      title: 'Startup Name Generator',
+      home: RandomWords(),
     );
   }

重新启动你的项目工程应用，你应该看到一个单词对列表。尽可能地向下滚动，你将继续看到新的单词对。
Restart the app. You should see a list of word pairings no matter how far you scroll.

Android

iOS

遇到问题？

Problems?

lib/main.dart

以 profile 模式运行

Profile or release runs

截止目前文档所示内容，你的应用应该运行在调试 (debug) 模式中，这个模式意味着在更大的性能开销下实现了更快速的开发效率，比如热重载功能的启用，因此你可能要面临较差质量的动画效果。当你准备分析应用性能或要打包发布的时候，你可能需要 Flutter 的 profile 或者 release 构建，相关文档，请查阅文档： Flutter 的构建模式选择。

So far you’ve been running your app in debug mode. Debug mode trades performance for useful developer features such as hot reload and step debugging. It’s not unexpected to see slow performance and janky animations in debug mode. Once you are ready to analyze performance or release your app, you’ll want to use Flutter’s “profile” or “release” build modes. For more details, see Flutter’s build modes.

下一步

Next steps

祝贺你！

Congratulations!

你已经完成了一个可以同时运行在 iOS 和 Android 平台的 Flutter 应用！同时收获了如下内容：

You’ve written an interactive Flutter app that runs on both iOS and Android. In this codelab, you’ve:

从零开始创建了一个 Flutter 应用；
Created a Flutter app from the ground up.
编写 Dart 代码；
Written Dart code.
使用外部的第三方库（package）；
Leveraged an external, third-party library.
在开发过程中试用了热重载 (hot reload)；
Used hot reload for a faster development cycle.
实现了一个有状态的 widget；
Implemented a stateful widget.
创建了一个懒加载的，无限滚动的列表。
Created a lazily loaded, infinite scrolling list.

如果你想继续扩展你的应用，在这里进行第二部分，你将会从以下方面修改你的应用：

If you would like to extend this app, proceed to part 2 on the Google Developers Codelabs site, where you add the following functionality:

为应用添加交互功能，一个能点击的小心心，来保存喜欢的公司名字；
Implement interactivity by adding a clickable heart icon to save favorite pairings.
为应用添加一个新的页面（Route），查看收藏列表；
Implement navigation to a new route by adding a new screen containing the saved favorites.
修改应用的主题，变成一个白色系的应用。
Modify the theme color, making an all-white app.

了解更多

基础
Flutter basics
应用其他平台开发经验
Apply your existing knowledge
其他资源
Other resources

通过下面的文档列表了解更多关于 Flutter 框架的内容：

Learn more about the Flutter framework from the following pages:

基础

Flutter basics

Widgets 介绍
Introduction to widgets
布局构建教程
Building layouts tutorial
为你的 Flutter 应用加入交互体验
Add interactivity tutorial

应用其他平台开发经验

Apply your existing knowledge

其他资源

Other resources

你还可以通过邮件列表与我们取得联系，我们非常乐意听到你的反馈！

Reach out to us at our mailing list. We’d love to hear from you!

Happy Fluttering!

给 Android 开发者的 Flutter 指南

视图 (Views)
Views
Intents
异步 UI
Async UI
工程结构和资源文件
Project structure & resources
Activity 和 Fragment
Activities and fragments
- Activity 和 Fragment 在 Flutter 中的对应概念是什么？
  What are the equivalent of activities and fragments in Flutter?
- 如何监听 Android Activity 的生命周期事件？
  How do I listen to Android activity lifecycle events?
布局
Layouts
手势监听和触摸事件处理
Gesture detection and touch event handling
- Flutter 中如何为一个 Widget 添加点击监听器？
  How do I add an onClick listener to a widget in Flutter?
- 如何处理 Widget 上的其它手势？
  How do I handle other gestures on widgets?
Listviews 和 adapters
Listviews & adapters
文字处理
Working with text
- 如何为 Text Widget 设置自定义字体？
  How do I set custom fonts on my Text widgets?
- 如何更改 Text Widget 的样式？
  How do I style my Text widgets?
表单输入
Form input
- Input 的“提示” (hint) 的对应概念是什么？
  What is the equivalent of a “hint” on an Input?
- 如何显示验证错误的信息？
  How do I show validation errors?
Flutter 插件
Flutter plugins
主题(Themes)
Themes
- 如何对应用使用主题？
  How do I theme my app?
数据库和本地存储
Databases and local storage
- 如何使用 Shared Preferences？
  How do I access Shared Preferences?
- 在 Flutter 中如何使用 SQLite？
  How do I access SQLite in Flutter?
Debugging
- 应该使用什么工具调试我的 Flutter 应用？
  What tools can I use to debug my app in Flutter?
通知
Notifications
- 如何设置推送通知？
  How do I set up push notifications?

这篇文档旨在帮助 Android 开发者利用既有的 Android 知识来通过 Flutter 开发移动应用。如果你了解 Android 框架的基本知识，你就可以使用这篇文档作为 Flutter 开发的快速入门。

This document is meant for Android developers looking to apply their existing Android knowledge to build mobile apps with Flutter. If you understand the fundamentals of the Android framework then you can use this document as a jump start to Flutter development.

你的 Android 知识和技能对于 Flutter 开发是非常有用的，因为 Flutter 依赖于 Android 操作系统的多种功能和配置。 Flutter 是一种全新的构建移动界面的方式，但是它有一套和 Android（以及 iOS）进行非 UI 任务通信的插件系统。如果你是一名 Android 专家，你就不必重新学习所有知识才能使用 Flutter。

Your Android knowledge and skill set are highly valuable when building with Flutter, because Flutter relies on the mobile operating system for numerous capabilities and configurations. Flutter is a new way to build UIs for mobile, but it has a plugin system to communicate with Android (and iOS) for non-UI tasks. If you’re an expert with Android, you don’t have to relearn everything to use Flutter.

这篇文档可以用作随时查阅以及答疑解惑的专题手册。

This document can be used as a cookbook by jumping around and finding questions that are most relevant to your needs.

视图 (Views)

Views

视图在 Flutter 中的对应概念是什么？

What is the equivalent of a View in Flutter?

Android 中的 View 是显示在屏幕上的一切的基础。按钮、工具栏、输入框以及一切内容都是 View。而 Flutter 中 View 的大致对应物是 Widget。 Widget 并非完全对应于 Android 中的 View，但是在你熟悉 Flutter 的工作原理的过程中可以把它们看做“声明和构建 UI 的方式”。

In Android, the View is the foundation of everything that shows up on the screen. Buttons, toolbars, and inputs, everything is a View. In Flutter, the rough equivalent to a View is a Widget. Widgets don’t map exactly to Android views, but while you’re getting acquainted with how Flutter works you can think of them as “the way you declare and construct UI”.

然而，widget 和 View 还是有一些差异。首先，widget 有着不一样的生命周期：它们是不可变的，一旦需要变化则生命周期终止。任何时候 widget 或它们的状态变化时， Flutter 框架都会创建一个新的 widget 树的实例。对比来看，一个 Android View 只会绘制一次，除非调用 invalidate 才会重绘。

However, these have a few differences to a View. To start, widgets have a different lifespan: they are immutable and only exist until they need to be changed. Whenever widgets or their state change, Flutter’s framework creates a new tree of widget instances. In comparison, an Android view is drawn once and does not redraw until invalidate is called.

Flutter 的 widget 很轻量，部分原因在于它们的不可变性。因为它们本身既非视图，也不会直接绘制任何内容，而是 UI 及其底层创建真正视图对象的语义的描述。

Flutter’s widgets are lightweight, in part due to their immutability. Because they aren’t views themselves, and aren’t directly drawing anything, but rather are a description of the UI and its semantics that get “inflated” into actual view objects under the hood.

Flutter 支持 Material Components 库。它提供实现了 Material Design 设计规范的 widgets。 Material Design 是一套为所有平台优化（包括 iOS）的灵活的设计系统。

Flutter includes the Material Components library. These are widgets that implement the Material Design guidelines. Material Design is a flexible design system optimized for all platforms, including iOS.

Flutter 非常灵活、有表达能力，它可以实现任何设计语言。例如，在 iOS 平台上，你可以使用 Cupertino widgets 创建 Apple 的 iOS 设计语言风格的界面。

But Flutter is flexible and expressive enough to implement any design language. For example, on iOS, you can use the Cupertino widgets to produce an interface that looks like Apple’s iOS design language.

如何更新 widgets？

How do I update widgets?

在 Android 中，你可以直接操作更新 View。然而在 Flutter 中， Widget 是不可变的，无法被直接更新，你需要操作 Widget 的状态。

In Android, you update your views by directly mutating them. However, in Flutter, Widgets are immutable and are not updated directly, instead you have to work with the widget’s state.

这就是有状态 (Stateful) 和无状态 (Stateless) Widget 概念的来源。 StatelessWidget 如其字面意思—没有状态信息的 Widget。

This is where the concept of Stateful and Stateless widgets comes from. A StatelessWidget is just what it sounds like—a widget with no state information.

StatelessWidget 用于你描述的用户界面的一部分不依赖于除了对象中的配置信息以外的任何东西的场景。

StatelessWidgets are useful when the part of the user interface you are describing does not depend on anything other than the configuration information in the object.

例如在 Android 中，这就像显示一个展示图标的 ImageView。这个图标在运行过程中不会改变，所以在 Flutter 中就使用 StatelessWidget。

For example, in Android, this is similar to placing an ImageView with your logo. The logo is not going to change during runtime, so use a StatelessWidget in Flutter.

如果你想要根据 HTTP 请求返回的数据或者用户的交互来动态地更新界面，那么你就必须使用 StatefulWidget，并告诉 Flutter 框架 Widget 的状态 (State) 更新了，以便 Flutter 可以更新这个 Widget。

If you want to dynamically change the UI based on data received after making an HTTP call or user interaction then you have to work with StatefulWidget and tell the Flutter framework that the widget’s State has been updated so it can update that widget.

这里需要着重注意的是，无状态和有状态的 Widget 本质上是行为一致的。它们每一帧都会重建，不同之处在于 StatefulWidget 有一个跨帧存储和恢复状态数据的 State 对象。

The important thing to note here is at the core both stateless and stateful widgets behave the same. They rebuild every frame, the difference is the StatefulWidget has a State object that stores state data across frames and restores it.

如果你有疑问，那么记住这条规则：如果一个 Widget 会变化（例如由于用户交互），它是有状态的。然而，如果一个 Widget 响应变化，它的父 Widget 只要本身不响应变化，就依然是无状态的。

If you are in doubt, then always remember this rule: if a widget changes (because of user interactions, for example) it’s stateful. However, if a widget reacts to change, the containing parent widget can still be stateless if it doesn’t itself react to change.

下面的例子展示了如何使用 StatelessWidget。Text Widget 是一个普通的 StatelessWidget。如果你查看 Text Widget 的实现，你会发现它继承自 StatelessWidget。

The following example shows how to use a StatelessWidget. A common StatelessWidget is the Text widget. If you look at the implementation of the Text widget you’ll find that it subclasses StatelessWidget.

Text(
  'I like Flutter!',
  style: TextStyle(fontWeight: FontWeight.bold),
);

如上所示，这个 Text Widget 没有相关联的状态信息，它只渲染传入构造器的信息，仅此而已。

As you can see, the Text Widget has no state information associated with it, it renders what is passed in its constructors and nothing more.

但是，假如你想要动态地改变 “I Like Flutter”，例如当你点击一个 FloatingActionButton 的时候，该怎么办呢？

But, what if you want to make “I Like Flutter” change dynamically, for example when clicking a FloatingActionButton?

为了实现这个效果，将 Text Widget 嵌入一个 StatefulWidget 中，并在用户点击按钮的时候更新它。

To achieve this, wrap the Text widget in a StatefulWidget and update it when the user clicks the button.

例如：

For example:

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  // Default placeholder text.
  String textToShow = 'I Like Flutter';

  void _updateText() {
    setState(() {
      // Update the text.
      textToShow = 'Flutter is Awesome!';
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: Center(child: Text(textToShow)),
      floatingActionButton: FloatingActionButton(
        onPressed: _updateText,
        tooltip: 'Update Text',
        child: Icon(Icons.update),
      ),
    );
  }
}

如何布局 Widget？我的 XML 布局文件在哪里？

How do I lay out my widgets? Where is my XML layout file?

在 Android 中，你通过 XML 文件定义布局，但是在 Flutter 中，你是通过一个 widget 树来定义布局的。

In Android, you write layouts in XML, but in Flutter you write your layouts with a widget tree.

以下示例展示了如何显示一个带有填充 (padding) 的简单 Widget：

The following example shows how to display a simple widget with padding:

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: Center(
        child: ElevatedButton(
          style: ElevatedButton.styleFrom(
            padding: EdgeInsets.only(left: 20.0, right: 30.0),
          ),
          onPressed: () {},
          child: Text('Hello'),
        ),
      ),
    );
  }

你可以在 widget 目录中查看 Flutter 提供的布局。

You can view some of the layouts that Flutter has to offer in the widget catalog.

如何在布局中添加或删除一个组件？

How do I add or remove a component from my layout?

在 Android 中，你通过调用父 View 的 addChild() 或 removeChild() 方法动态地添加或者删除子 View。在 Flutter 中，由于 Widget 是不可变的，所以没有 addChild() 的直接对应的方法。不过，你可以给返回一个 Widget 的父 Widget 传入一个方法，并通过布尔标记值控制子 Widget 的创建。

In Android, you call addChild() or removeChild() on a parent to dynamically add or remove child views. In Flutter, because widgets are immutable there is no direct equivalent to addChild(). Instead, you can pass a function to the parent that returns a widget, and control that child’s creation with a boolean flag.

例如，下面就是你可以如何在点击一个 FloatingActionButton 的时候在两个 Widget 之间切换。

For example, here is how you can toggle between two widgets when you click on a FloatingActionButton:

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  // Default value for toggle.
  bool toggle = true;
  void _toggle() {
    setState(() {
      toggle = !toggle;
    });
  }

  Widget _getToggleChild() {
    if (toggle) {
      return Text('Toggle One');
    } else {
      return ElevatedButton(
        onPressed: () {},
        child: Text('Toggle Two'),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: Center(
        child: _getToggleChild(),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _toggle,
        tooltip: 'Update Text',
        child: Icon(Icons.update),
      ),
    );
  }
}

How do I animate a widget?

在 Android 中，你既可以通过 XML 文件定义动画，也可以调用 View 对象的 animate() 方法。在 Flutter 里，则使用动画库，通过将 Widget 嵌入一个动画 Widget 的方式实现 Widget 的动画效果。

In Android, you either create animations using XML, or call the animate() method on a view. In Flutter, animate widgets using the animation library by wrapping widgets inside an animated widget.

Flutter 通过 Animation<double> 的子类 AnimationController 来暂停、播放、停止以及逆向播放动画。它需要一个 Ticker 在垂直同步 (vsync) 的时候发出信号，并且在运行的时候创建一个介于 0 和 1 之间的线性插值。然后你就可以创建一个或多个 Animation，并将它们绑定到控制器上。

In Flutter, use an AnimationController which is an Animation<double> that can pause, seek, stop and reverse the animation. It requires a Ticker that signals when vsync happens, and produces a linear interpolation between 0 and 1 on each frame while it’s running. You then create one or more Animations and attach them to the controller.

例如，你可以使用 CurvedAnimation 来实现一个曲线插值的动画。在这种情况下，控制器决定了动画进度，CurvedAnimation 计算用于替换控制器默认线性动画的曲线值。和 Widget 一样，Flutter 中的动画效果也可以组合使用。

For example, you might use CurvedAnimation to implement an animation along an interpolated curve. In this sense, the controller is the “master” source of the animation progress and the CurvedAnimation computes the curve that replaces the controller’s default linear motion. Like widgets, animations in Flutter work with composition.

在构建 Widget 树的时候，你需要将 Animation 对象赋值给某个 Widget 的动画属性，例如 FadeTransition 的不透明度属性，并让控制器开始动画。

When building the widget tree you assign the Animation to an animated property of a widget, such as the opacity of a FadeTransition, and tell the controller to start the animation.

下面的例子展示了如何实现一个点击 FloatingActionButton 的时候将一个 Widget 渐变为一个图标的 FadeTransition：

The following example shows how to write a FadeTransition that fades the widget into a logo when you press the FloatingActionButton:

import 'package:flutter/material.dart';

void main() {
  runApp(FadeAppTest());
}

class FadeAppTest extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Fade Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyFadeTest(title: 'Fade Demo'),
    );
  }
}

class MyFadeTest extends StatefulWidget {
  MyFadeTest({Key? key, required this.title}) : super(key: key);
  final String title;
  @override
  _MyFadeTest createState() => _MyFadeTest();
}

class _MyFadeTest extends State<MyFadeTest> with TickerProviderStateMixin {
  late AnimationController controller;
  late CurvedAnimation curve;

  @override
  void initState() {
    super.initState();
    controller = AnimationController(
      duration: const Duration(milliseconds: 2000),
      vsync: this,
    );
    curve = CurvedAnimation(
      parent: controller,
      curve: Curves.easeIn,
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: FadeTransition(
          opacity: curve,
          child: FlutterLogo(
            size: 100.0,
          ),
        ),
      ),
      floatingActionButton: FloatingActionButton(
        tooltip: 'Fade',
        onPressed: () {
          controller.forward();
        },
        child: Icon(Icons.brush),
      ),
    );
  }
}

获取更多内容，请查看动画 Widget，动画指南以及动画概览。

For more information, see Animation & Motion widgets, the Animations tutorial, and the Animations overview.

如何使用 Canvas 进行绘制？

How do I use a Canvas to draw/paint?

在 Android 中，你可以使用 Canvas 和 Drawable 将图片和形状绘制到屏幕上。Flutter 也有一个类似于 Canvas 的 API，因为它基于相同的底层渲染引擎 Skia。因此，在 Flutter 中用画布 (canvas) 进行绘制对于 Android 开发者来说是一件非常熟悉的工作。

In Android, you would use the Canvas and Drawables to draw images and shapes to the screen. Flutter has a similar Canvas API as well, since it is based on the same low-level rendering engine, Skia. As a result, painting to a canvas in Flutter is a very familiar task for Android developers.

Flutter 有两个帮助你用画布 (canvas) 进行绘制的类：CustomPaint 和 CustomPainter，后者可以实现自定义的绘制算法。

Flutter has two classes that help you draw to the canvas: CustomPaint and CustomPainter, the latter of which implements your algorithm to draw to the canvas.

如果想学习在 Flutter 中如何实现一个签名功能，可以查看 Collin 在 Custom Paint 上的回答。

To learn how to implement a signature painter in Flutter, see Collin’s answer on Custom Paint.

import 'package:flutter/material.dart';

void main() => runApp(MaterialApp(home: DemoApp()));

class DemoApp extends StatelessWidget {
  Widget build(BuildContext context) => Scaffold(body: Signature());
}

class Signature extends StatefulWidget {
  SignatureState createState() => SignatureState();
}

class SignatureState extends State<Signature> {
  List<Offset?> _points = <Offset>[];
  Widget build(BuildContext context) {
    return GestureDetector(
      onPanUpdate: (DragUpdateDetails details) {
        setState(() {
          RenderBox? referenceBox = context.findRenderObject() as RenderBox;
          Offset localPosition = referenceBox.globalToLocal(details.globalPosition);
          _points = List.from(_points)..add(localPosition);
        });
      },
      onPanEnd: (DragEndDetails details) => _points.add(null),
      child: CustomPaint(
        painter: SignaturePainter(_points),
        size: Size.infinite,
      ),
    );
  }
}

class SignaturePainter extends CustomPainter {
  SignaturePainter(this.points);
  final List<Offset?> points;
  void paint(Canvas canvas, Size size) {
    var paint = Paint()
      ..color = Colors.black
      ..strokeCap = StrokeCap.round
      ..strokeWidth = 5.0;
    for (int i = 0; i < points.length - 1; i++) {
      if (points[i] != null && points[i + 1] != null)
        canvas.drawLine(points[i]!, points[i + 1]!, paint);
    }
  }

  bool shouldRepaint(SignaturePainter other) => other.points != points;
}

如何创建自定义 Widget？

How do I build custom widgets?

在 Android 中，一般通过继承 View 类，或者使用已有的视图类，再覆写或实现可以达到特定效果的方法。

In Android, you typically subclass View, or use a pre-existing view, to override and implement methods that achieve the desired behavior.

在 Flutter 中，通过组合更小的 Widget 来创建自定义 Widget（而不是继承它们）。这和 Android 中实现一个自定义的 ViewGroup 有些类似，所有的构建 UI 的模块代码都在手边，不过由你提供不同的行为—例如，自定义布局 (layout) 逻辑。

In Flutter, build a custom widget by composing smaller widgets (instead of extending them). It is somewhat similar to implementing a custom ViewGroup in Android, where all the building blocks are already existing, but you provide a different behavior—for example, custom layout logic.

举例来说，你该如何创建一个在构造器接收标签参数的 CustomButton？你要组合 RaisedButton 和一个标签来创建自定义按钮，而不是继承 RaisedButton：

For example, how do you build a CustomButton that takes a label in the constructor? Create a CustomButton that composes a ElevatedButton with a label, rather than by extending ElevatedButton:

class CustomButton extends StatelessWidget {
  final String label;

  CustomButton(this.label);

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {},
      child: Text(label),
    );
  }
}

然后就像使用其它 Flutter Widget 一样使用 CustomButton：

Then use CustomButton, just as you’d use any other Flutter widget:

@override
Widget build(BuildContext context) {
  return Center(
    child: CustomButton("Hello"),
  );
}

Intents

`Intent` 在 Flutter 中的对应概念是什么？

What is the equivalent of an Intent in Flutter?

在 Android 中，Intent 主要有两个使用场景：在 Activity 之前进行导航，以及组件间通信。 Flutter 却没有 intent 这样的概念，但是你依然可以通过原生集成 (插件) 来启动 intent。

In Android, there are two main use cases for Intents: navigating between Activities, and communicating with components. Flutter, on the other hand, does not have the concept of intents, although you can still start intents through native integrations (using a plugin).

Flutter 实际上并没有 Activity 和 Fragment 的对应概念。在 Flutter 中你需要使用 Navigator 和 Route 在同一个 Activity 内的不同界面间进行跳转。

Flutter doesn’t really have a direct equivalent to activities and fragments; rather, in Flutter you navigate between screens, using a Navigator and Routes, all within the same Activity.

Route 是应用内屏幕和页面的抽象，Navigator 是管理路径 route 的工具。一个 route 对象大致对应于一个 Activity，但是它的含义是不一样的。Navigator 可以通过对 route 进行压栈和弹栈操作实现页面的跳转。Navigator 的工作原理和栈相似，你可以将想要跳转到的 route 压栈 (push())，想要返回的时候将 route 弹栈 (pop())。

A Route is an abstraction for a “screen” or “page” of an app, and a Navigator is a widget that manages routes. A route roughly maps to an Activity, but it does not carry the same meaning. A navigator can push and pop routes to move from screen to screen. Navigators work like a stack on which you can push() new routes you want to navigate to, and from which you can pop() routes when you want to “go back”.

在 Android 中，在应用的 AndroidManifest.xml 文件中声明 Activity。

In Android, you declare your activities inside the app’s AndroidManifest.xml.

在 Flutter 中，你有多种不同的方式在页面间导航：

In Flutter, you have a couple options to navigate between pages:

定义一个 route 名字的 Map。(MaterialApp)
Specify a Map of route names. (MaterialApp)
直接导航到一个 route。(WidgetApp)
Directly navigate to a route. (WidgetApp)

下面的例子创建了一个 Map。

The following example builds a Map.

void main() {
 runApp(MaterialApp(
   home: MyAppHome(), // Becomes the route named '/'.
   routes: <String, WidgetBuilder> {
     '/a': (BuildContext context) => MyPage(title: 'page A'),
     '/b': (BuildContext context) => MyPage(title: 'page B'),
     '/c': (BuildContext context) => MyPage(title: 'page C'),
   },
 ));
}

通过将 route 名压栈 (push) 到 Navigator 中来跳转到这个 route。

Navigate to a route by pushing its name to the Navigator.

Navigator.of(context).pushNamed('/b');

Intent 的另一种常见的使用场景是调用外部的组件，例如相机或文件选择器。对于这种情况，你需要创建一个原生平台插件（或者使用已有的插件）。

The other popular use-case for Intents is to call external components such as a Camera or File picker. For this, you would need to create a native platform integration (or use an existing plugin).

想要学习如何创建一个原生平台集成，请查看开发包和插件。

To learn how to build a native platform integration, see developing packages and plugins.

在 Flutter 中应该如何处理从外部应用接收到的 intent？

How do I handle incoming intents from external applications in Flutter?

Flutter 可以通过直接和 Android 层通信并请求分享的数据来处理接收到的 Android intent。

Flutter can handle incoming intents from Android by directly talking to the Android layer and requesting the data that was shared.

下面的例子中，运行 Flutter 代码的原生 Activity 注册了一个文本分享的 intent 过滤器，这样其它应用就可以和 Flutter 应用分享文本了。

The following example registers a text share intent filter on the native activity that runs our Flutter code, so other apps can share text with our Flutter app.

从以上流程可以得知，我们首先在 Android 原生层面（在我们的 Activity 中）处理分享的文本数据，然后 Flutter 再通过使用 MethodChannel 获取这个数据。

The basic flow implies that we first handle the shared text data on the Android native side (in our Activity), and then wait until Flutter requests for the data to provide it using a MethodChannel.

首先，在 AndroidManifest.xml 中注册 intent 过滤器：

First, register the intent filter for all intents in AndroidManifest.xml:

<activity
  android:name=".MainActivity"
  android:launchMode="singleTop"
  android:theme="@style/LaunchTheme"
  android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection"
  android:hardwareAccelerated="true"
  android:windowSoftInputMode="adjustResize">
  <!-- ... -->
  <intent-filter>
    <action android:name="android.intent.action.SEND" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:mimeType="text/plain" />
  </intent-filter>
</activity>

接着在 MainActivity 中处理 intent，提取出其它 intent 分享的文本并保存。当 Flutter 准备好处理的时候，它会使用一个平台通道请求数据，数据便会从原生端发送过来：

Then in MainActivity, handle the intent, extract the text that was shared from the intent, and hold onto it. When Flutter is ready to process, it requests the data using a platform channel, and it’s sent across from the native side:

package com.example.shared;

import android.content.Intent;
import android.os.Bundle;

import androidx.annotation.NonNull;

import io.flutter.plugin.common.MethodChannel;
import io.flutter.embedding.android.FlutterActivity;
import io.flutter.embedding.engine.FlutterEngine;
import io.flutter.plugins.GeneratedPluginRegistrant;

public class MainActivity extends FlutterActivity {

  private String sharedText;
  private static final String CHANNEL = "app.channel.shared.data";

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Intent intent = getIntent();
    String action = intent.getAction();
    String type = intent.getType();

    if (Intent.ACTION_SEND.equals(action) && type != null) {
      if ("text/plain".equals(type)) {
        handleSendText(intent); // Handle text being sent
      }
    }
  }

  @Override
  public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
      GeneratedPluginRegistrant.registerWith(flutterEngine);

      new MethodChannel(flutterEngine.getDartExecutor().getBinaryMessenger(), CHANNEL)
              .setMethodCallHandler(
                      (call, result) -> {
                          if (call.method.contentEquals("getSharedText")) {
                              result.success(sharedText);
                              sharedText = null;
                          }
                      }
              );
  }

  void handleSendText(Intent intent) {
    sharedText = intent.getStringExtra(Intent.EXTRA_TEXT);
  }
}

最后，当 Widget 渲染的时候，从 Flutter 这端请求数据：

Finally, request the data from the Flutter side when the widget is rendered:

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample Shared App Handler',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  static const platform = MethodChannel('app.channel.shared.data');
  String dataShared = 'No data';

  @override
  void initState() {
    super.initState();
    getSharedText();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(body: Center(child: Text(dataShared)));
  }

  void getSharedText() async {
    var sharedData = await platform.invokeMethod('getSharedText');
    if (sharedData != null) {
      setState(() {
        dataShared = sharedData;
      });
    }
  }
}

`startActivityForResult()` 的对应方法是什么？

What is the equivalent of startActivityForResult()?

Navigator 类负责 Flutter 的导航，并用来接收被压栈的 route 的返回值。这是通过在 push() 后返回的 Future 上 await 来实现的。

The Navigator class handles routing in Flutter and is used to get a result back from a route that you have pushed on the stack. This is done by awaiting on the Future returned by push().

例如，要打开一个让用户选择位置的 route，你可以这样做：

For example, to start a location route that lets the user select their location, you could do the following:

Map coordinates = await Navigator.of(context).pushNamed('/location');

然后，在你的位置 route 内，一旦用户选择了位置，你就可以弹栈 (pop) 并返回结果：

And then, inside your location route, once the user has selected their location you can pop the stack with the result:

Navigator.of(context).pop({"lat":43.821757,"long":-79.226392});

异步 UI

Async UI

`runOnUiThread()` 在 Flutter 中的对应方法是什么？

What is the equivalent of runOnUiThread() in Flutter?

Dart 有一个单线程执行的模型，同时也支持 Isolate （在另一个线程运行 Dart 代码的方法），它是一个事件循环和异步编程方式。除非你创建一个 Isolate，否则你的 Dart 代码会运行在主 UI 线程，并被一个事件循环所驱动。Flutter 的事件循环对应于 Android 里的主 Looper— 也即绑定到主线程上的 Looper。

Dart has a single-threaded execution model, with support for Isolates (a way to run Dart code on another thread), an event loop, and asynchronous programming. Unless you spawn an Isolate, your Dart code runs in the main UI thread and is driven by an event loop. Flutter’s event loop is equivalent to Android’s main Looper—that is, the Looper that is attached to the main thread.

Dart 的单线程模型并不意味着你需要以会导致 UI 冻结的阻塞操作的方式来运行所有代码。不同于 Android 中需要你时刻保持主线程空闲，在 Flutter 中，可以使用 Dart 语言提供的异步工具，例如 async/await 来执行异步任务。如果你使用过 C# 或者 Javascript 中的 async/await 范式，或者 Kotlin 中的协程，你应该对它比较熟悉。

Dart’s single-threaded model doesn’t mean you need to run everything as a blocking operation that causes the UI to freeze. Unlike Android, which requires you to keep the main thread free at all times, in Flutter, use the asynchronous facilities that the Dart language provides, such as async/await, to perform asynchronous work. You might be familiar with the async/await paradigm if you’ve used it in C#, Javascript, or if you have used Kotlin’s coroutines.

例如，你可以通过使用 async/await 来运行网络代码而且不会导致 UI 挂起，同时让 Dart 来处理背后的繁重细节：

For example, you can run network code without causing the UI to hang by using async/await and letting Dart do the heavy lifting:

Future<void> loadData() async {
  var dataURL = Uri.parse('https://jsonplaceholder.typicode.com/posts');
  http.Response response = await http.get(dataURL);
  setState(() {
    widgets = jsonDecode(response.body);
  });
}

一旦用 await 修饰的网络操作完成，再调用 setState() 更新 UI，这会触发 widget 子树的重建并更新数据。

Once the awaited network call is done, update the UI by calling setState(), which triggers a rebuild of the widget sub-tree and updates the data.

下面的例子展示了异步加载数据并将之展示在 ListView 内：

The following example loads data asynchronously and displays it in a ListView:

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List widgets = [];

  @override
  void initState() {
    super.initState();
    loadData();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: ListView.builder(
        itemCount: widgets.length,
        itemBuilder: (BuildContext context, int position) {
          return getRow(position);
        },
      ),
    );
  }

  Widget getRow(int i) {
    return Padding(
      padding: EdgeInsets.all(10.0),
      child: Text("Row ${widgets[i]["title"]}"),
    );
  }

  Future<void> loadData() async {
    var dataURL = Uri.parse('https://jsonplaceholder.typicode.com/posts');
    http.Response response = await http.get(dataURL);
    setState(() {
      widgets = jsonDecode(response.body);
    });
  }
}

参考下一节内容获取更多关于后台任务以及 Flutter 与 Android 的差异的信息。

Refer to the next section for more information on doing work in the background, and how Flutter differs from Android.

如何将任务转移到后台线程？

How do you move work to a background thread?

在 Android 中，当你想要访问一个网络资源却又不想阻塞主线程并避免 ANR 的时候，你一般会将任务放到一个后台线程中运行。例如，你可以使用一个 AsyncTask、一个 LiveData、一个 IntentService、一个 JobScheduler 任务或者通过 RxJava 的管道用调度器将任务切换到后台线程中。

In Android, when you want to access a network resource you would typically move to a background thread and do the work, as to not block the main thread, and avoid ANRs. For example, you might be using an AsyncTask, a LiveData, an IntentService, a JobScheduler job, or an RxJava pipeline with a scheduler that works on background threads.

由于 Flutter 是单线程并且运行一个事件循环（类似 Node.js），你无须担心线程的管理以及后台线程的创建。如果你在执行和 I/O 绑定的任务，例如存储访问或者网络请求，那么你可以安全地使用 async/await，并无后顾之忧。再例如，你需要执行消耗 CPU 的计算密集型工作，那么你可以将其转移到一个 Isolate 上以避免阻塞事件循环，就像你在 Android 中会将任何任务放到主线程之外一样。

Since Flutter is single threaded and runs an event loop (like Node.js), you don’t have to worry about thread management or spawning background threads. If you’re doing I/O-bound work, such as disk access or a network call, then you can safely use async/await and you’re all set. If, on the other hand, you need to do computationally intensive work that keeps the CPU busy, you want to move it to an Isolate to avoid blocking the event loop, like you would keep any sort of work out of the main thread in Android.

对于和 I/O 绑定的任务，将方法声明为 async 方法，并在方法内 await 一个长时间运行的任务：

For I/O-bound work, declare the function as an async function, and await on long-running tasks inside the function:

Future<void> loadData() async {
  var dataURL = Uri.parse('https://jsonplaceholder.typicode.com/posts');
  http.Response response = await http.get(dataURL);
  setState(() {
    widgets = jsonDecode(response.body);
  });
}

这就是你一般应该如何执行网络和数据库操作，它们都属于 I/O 操作。

This is how you would typically do network or database calls, which are both I/O operations.

在 Android 中，当你继承 AsyncTask 的时候，你一般会覆写三个方法： onPreExecute()、doInBackground() 和 onPostExecute()。 Flutter 中没有对应的 API，你只需要 await 一个耗时方法调用， Dart 的事件循环就会帮你处理剩下的事情。

On Android, when you extend AsyncTask, you typically override 3 methods, onPreExecute(), doInBackground() and onPostExecute(). There is no equivalent in Flutter, since you await on a long running function, and Dart’s event loop takes care of the rest.

然而，有时候你可能需要处理大量的数据并挂起你的 UI。在 Flutter 中，可以通过使用 Isolate 来利用多核处理器的优势执行耗时或计算密集的任务。

However, there are times when you might be processing a large amount of data and your UI hangs. In Flutter, use Isolates to take advantage of multiple CPU cores to do long-running or computationally intensive tasks.

Isolate 是独立执行的线程，不会和主执行内存堆分享内存。这意味着你无法访问主线程的变量，或者调用 setState() 更新 UI。不同于 Android 中的线程，Isolate 如其名所示，它们无法分享内存（例如通过静态变量的形式）。

Isolates are separate execution threads that do not share any memory with the main execution memory heap. This means you can’t access variables from the main thread, or update your UI by calling setState(). Unlike Android threads, Isolates are true to their name, and cannot share memory (in the form of static fields, for example).

下面的例子展示了一个简单的 Isolate 是如何将数据分享给主线程来更新 UI 的。

The following example shows, in a simple isolate, how to share data back to the main thread to update the UI.

Future<void> loadData() async {
  ReceivePort receivePort = ReceivePort();
  await Isolate.spawn(dataLoader, receivePort.sendPort);

  // The 'echo' isolate sends its SendPort as the first message.
  SendPort sendPort = await receivePort.first;

  List msg = await sendReceive(
    sendPort,
    "https://jsonplaceholder.typicode.com/posts",
  );

  setState(() {
    widgets = msg;
  });
}

// The entry point for the isolate.
static Future<void> dataLoader(SendPort sendPort) async {
  // Open the ReceivePort for incoming messages.
  ReceivePort port = ReceivePort();

  // Notify any other isolates what port this isolate listens to.
  sendPort.send(port.sendPort);

  await for (var msg in port) {
    String data = msg[0];
    SendPort replyTo = msg[1];

    String dataURL = data;
    http.Response response = await http.get(dataURL);
    // Lots of JSON to parse
    replyTo.send(jsonDecode(response.body));
  }
}

Future sendReceive(SendPort port, msg) {
  ReceivePort response = ReceivePort();
  port.send([msg, response.sendPort]);
  return response.first;
}

这里的 dataLoader() 就是运行在自己独立执行线程内的 Isolate。在 Isolate 中你可以执行更多的 CPU 密集型操作（例如解析一个大的 JSON 数据），或者执行计算密集型的数学运算，例如加密或信号处理。

Here, dataLoader() is the Isolate that runs in its own separate execution thread. In the isolate you can perform more CPU intensive processing (parsing a big JSON, for example), or perform computationally intensive math, such as encryption or signal processing.

你可以运行下面这个完整的例子：

You can run the full example below:

import 'dart:async';
import 'dart:convert';
import 'dart:isolate';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List widgets = [];

  @override
  void initState() {
    super.initState();
    loadData();
  }

  Widget getBody() {
    bool showLoadingDialog = widgets.isEmpty;
    if (showLoadingDialog) {
      return getProgressDialog();
    } else {
      return getListView();
    }
  }

  Widget getProgressDialog() {
    return Center(child: CircularProgressIndicator());
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: getBody(),
    );
  }

  ListView getListView() {
    return ListView.builder(
      itemCount: widgets.length,
      itemBuilder: (BuildContext context, int position) {
        return getRow(position);
      },
    );
  }

  Widget getRow(int i) {
    return Padding(
      padding: EdgeInsets.all(10.0),
      child: Text("Row ${widgets[i]["title"]}"),
    );
  }

  Future<void> loadData() async {
    ReceivePort receivePort = ReceivePort();
    await Isolate.spawn(dataLoader, receivePort.sendPort);

    // The 'echo' isolate sends its SendPort as the first message.
    SendPort sendPort = await receivePort.first;

    List msg = await sendReceive(
      sendPort,
      'https://jsonplaceholder.typicode.com/posts',
    );

    setState(() {
      widgets = msg;
    });
  }

  // The entry point for the isolate.
  static Future<void> dataLoader(SendPort sendPort) async {
    // Open the ReceivePort for incoming messages.
    ReceivePort port = ReceivePort();

    // Notify any other isolates what port this isolate listens to.
    sendPort.send(port.sendPort);

    await for (var msg in port) {
      String data = msg[0];
      SendPort replyTo = msg[1];

      String dataURL = data;
      http.Response response = await http.get(dataURL);
      // Lots of JSON to parse
      replyTo.send(jsonDecode(response.body));
    }
  }

  Future sendReceive(SendPort port, msg) {
    ReceivePort response = ReceivePort();
    port.send([msg, response.sendPort]);
    return response.first;
  }
}

OkHttp 在 Flutter 中的对应物是什么？

What is the equivalent of OkHttp on Flutter?

Flutter 中使用流行的 http 包进行网络请求是很简单的。

Making a network call in Flutter is easy when you use the popular http package.

虽然 http 包没有 OkHttp 中的所有功能，但是它抽象了很多通常你会自己实现的网络功能，这使其本身在执行网络请求时简单易用。

While the http package doesn’t have every feature found in OkHttp, it abstracts away much of the networking that you would normally implement yourself, making it a simple way to make network calls.

如果要使用 http 包，需要在 pubspec.yaml 文件中添加依赖：

To use the http package, add it to your dependencies in pubspec.yaml:

dependencies:
  ...
  http: ^0.11.3+16

如果要发起一个网络请求，在异步 (async) 方法 http.get() 上调用 await 即可：

To make a network call, call await on the async function http.get():

import 'dart:convert';

import 'package:http/http.dart' as http;
// ...

Future<void> loadData() async {
  var dataURL = Uri.parse('https://jsonplaceholder.typicode.com/posts');
  http.Response response = await http.get(dataURL);
  setState(() {
    widgets = jsonDecode(response.body);
  });
}

如何为耗时任务显示进度？

How do I show the progress for a long-running task?

在 Android 中你通常会在后台执行一个耗时任务的时候显示一个 ProgressBar 在界面上。

In Android you would typically show a ProgressBar view in your UI while executing a long running task on a background thread.

在 Flutter 中，我们使用 ProgressIndicator widget。通过代码逻辑使用一个布尔标记值控制进度条的渲染。

In Flutter, use a ProgressIndicator widget. Show the progress programmatically by controlling when it’s rendered through a boolean flag. Tell Flutter to update its state before your long-running task starts, and hide it after it ends.

在下面的例子中，build 方法被拆分成三个不同的方法。如果 showLoadingDialog() 返回 true（当 widgets.length == 0），渲染 ProgressIndicator。否则，在 ListView 里渲染网络请求返回的数据。

In the following example, the build function is separated into three different functions. If showLoadingDialog is true (when widgets.isEmpty), then render the ProgressIndicator. Otherwise, render the ListView with the data returned from a network call.

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List widgets = [];

  @override
  void initState() {
    super.initState();
    loadData();
  }

  Widget getBody() {
    bool showLoadingDialog = widgets.isEmpty;
    if (showLoadingDialog) {
      return getProgressDialog();
    } else {
      return getListView();
    }
  }

  Widget getProgressDialog() {
    return Center(child: CircularProgressIndicator());
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: getBody(),
    );
  }

  ListView getListView() {
    return ListView.builder(
      itemCount: widgets.length,
      itemBuilder: (BuildContext context, int position) {
        return getRow(position);
      },
    );
  }

  Widget getRow(int i) {
    return Padding(
      padding: EdgeInsets.all(10.0),
      child: Text("Row ${widgets[i]["title"]}"),
    );
  }

  Future<void> loadData() async {
    var dataURL = Uri.parse('https://jsonplaceholder.typicode.com/posts');
    http.Response response = await http.get(dataURL);
    setState(() {
      widgets = jsonDecode(response.body);
    });
  }
}

工程结构和资源文件

Project structure & resources

在哪里放置分辨率相关的图片文件？

Where do I store my resolution-dependent image files?

虽然 Android 区分对待资源文件 (resources) 和资产文件 (assets)，但是 Flutter 应用只有资产文件 (assets)。所有原本在 Android 中应该放在 res/drawable-* 文件夹中的资源文件，在 Flutter 中都放在一个 assets 文件夹中。

While Android treats resources and assets as distinct items, Flutter apps have only assets. All resources that would live in the res/drawable-* folders on Android, are placed in an assets folder for Flutter.

Flutter 遵循一个简单的类似 iOS 的密度相关的格式。文件可以是一倍 (1.0x)、两倍 (2.0x)、三倍 (3.0x) 或其它的任意倍数。 Flutter 没有 dp 单位，但是有逻辑像素尺寸，基本和设备无关的像素尺寸是一样的。名称为 devicePixelRatio 的尺寸表示在单一逻辑像素标准下设备物理像素的比例。

Flutter follows a simple density-based format like iOS. Assets might be 1.0x, 2.0x, 3.0x, or any other multiplier. Flutter doesn’t have dps but there are logical pixels, which are basically the same as device-independent pixels. The so-called devicePixelRatio expresses the ratio of physical pixels in a single logical pixel.

和 Android 的密度分类的对照表如下：

The equivalent to Android’s density buckets are:

Android 密度修饰符 Android density qualifier	Flutter 像素比例 Flutter pixel ratio
`ldpi`	`0.75x`
`mdpi`	`1.0x`
`hdpi`	`1.5x`
`xhdpi`	`2.0x`
`xxhdpi`	`3.0x`
`xxxhdpi`	`4.0x`

文件放置于任意文件夹中—Flutter 没有预先定义好的文件夹结构。你在 pubspec.yaml 文件中定义文件（包括位置信息），Flutter 负责找到它们。

Assets are located in any arbitrary folder—Flutter has no predefined folder structure. You declare the assets (with location) in the pubspec.yaml file, and Flutter picks them up.

需要注意的是，在 Flutter 1.0 beta 2 之前，在 Flutter 中定义的文件不能被原生端访问，反之亦然。原生端定义的资产文件 (assets) 和资源文件 (resources) 也无法被 Flutter 访问，因为它们是放置于不同的文件夹中的。

Note that before Flutter 1.0 beta 2, assets defined in Flutter were not accessible from the native side, and vice versa, native assets and resources weren’t available to Flutter, as they lived in separate folders.

至于 Flutter beta 2，文件是放置于原生端的 asset 文件夹中，所以可以被原生端的 AssetManager 访问：

As of Flutter beta 2, assets are stored in the native asset folder, and are accessed on the native side using Android’s AssetManager:

val flutterAssetStream = assetManager.open("flutter_assets/assets/my_flutter_asset.png")

然而对于 Flutter beta 2，Flutter 依然无法访问原生资源文件 (resources)，也无法访问原生资产文件 (assets)。

As of Flutter beta 2, Flutter still cannot access native resources, nor it can access native assets.

如果你要向 Flutter 项目中添加一个新的叫 my_icon.png 的图片资源，并且将其放入我们随便起名的叫做 images 的文件夹中，你需要将基础图片(1.0x)放在 images 文件夹中，并将其它倍数的图片放入以特定倍数作为名称的子文件夹中：

To add a new image asset called my_icon.png to our Flutter project, for example, and deciding that it should live in a folder we arbitrarily called images, you would put the base image (1.0x) in the images folder, and all the other variants in sub-folders called with the appropriate ratio multiplier:

images/my_icon.png       // Base: 1.0x image
images/2.0x/my_icon.png  // 2.0x image
images/3.0x/my_icon.png  // 3.0x image

接下来，你需要在 pubspec.yaml 文件中定义这些图片：

Next, you’ll need to declare these images in your pubspec.yaml file:

assets:
 - images/my_icon.jpeg

然后你就可以使用 AssetImage 访问你的图片了：

You can then access your images using AssetImage:

AssetImage('images/my_icon.jpeg');

或者通过 Image widget 直接访问：

or directly in an Image widget:

@override
Widget build(BuildContext context) {
  return Image.asset('images/my_image.png');
}

字符串储存在哪里？如何处理本地化？

Where do I store strings? How do I handle localization?

Flutter 当下并没有一个特定的管理字符串的资源管理系统。目前来讲，最好的办法是将字符串作为静态域存放在类中，并通过类访问它们。例如：

Flutter currently doesn’t have a dedicated resources-like system for strings. At the moment, the best practice is to hold your copy text in a class as static fields and accessing them from there. For example:

class Strings {
  static String welcomeMessage = 'Welcome To Flutter';
}

接着在你们的代码中，你可以这样访问你的字符串：

Then in your code, you can access your strings as such:

Text(Strings.welcomeMessage)

Flutter 在 Android 上提供无障碍的基本支持，但是这个功能当下仍在开发。

Flutter has basic support for accessibility on Android, though this feature is a work in progress.

我们鼓励 Flutter 开发者使用 intl 包进行国际化和本地化。

Flutter developers are encouraged to use the intl package for internationalization and localization.

Gradle 文件的对应物是什么？我该如何添加依赖？

What is the equivalent of a Gradle file? How do I add dependencies?

在 Android 中，你在 Gradle 构建脚本中添加依赖。Flutter 使用 Dart 自己的构建系统以及 Pub 包管理器。构建工具会将原生 Android 和 iOS 壳应用的构建代理给对应的构建系统。

In Android, you add dependencies by adding to your Gradle build script. Flutter uses Dart’s own build system, and the Pub package manager. The tools delegate the building of the native Android and iOS wrapper apps to the respective build systems.

虽然在你的 Flutter 项目的 android 文件夹下有 Gradle 文件，但是它们只用于给对应平台的集成添加原生依赖。一般来说，在 pubspec.yaml 文件中定义在 Flutter 里使用的外部依赖。 pub.dev 是查找 Flutter packages 的好地方。

While there are Gradle files under the android folder in your Flutter project, only use these if you are adding native dependencies needed for per-platform integration. In general, use pubspec.yaml to declare external dependencies to use in Flutter. A good place to find Flutter packages is pub.dev.

Activity 和 Fragment

Activities and fragments

Activity 和 Fragment 在 Flutter 中的对应概念是什么？

What are the equivalent of activities and fragments in Flutter?

在 Android 中，一个 Activity 代表用户可以完成的一件独立任务。一个 Fragment 代表一个行为或者用户界面的一部分。 Fragment 用于模块化你的代码，为大屏组合复杂的用户界面，并适配应用的界面。在 Flutter 中，这两个概念都对应于 Widget。

In Android, an Activity represents a single focused thing the user can do. A Fragment represents a behavior or a portion of user interface. Fragments are a way to modularize your code, compose sophisticated user interfaces for larger screens, and help scale your application UI. In Flutter, both of these concepts fall under the umbrella of Widgets.

如果要学习更多的关于 Activity 和 Fragment 创建界面的内容，请阅读社区贡献的 Medium 文章，给 Android 开发者的 Flutter 指南：如何在 Flutter 中设计一个 Activity 界面。

To learn more about the UI for building Activities and Fragements, see the community-contributed Medium article, Flutter for Android Developers: How to design Activity UI in Flutter.

就如在 Intents 部分所提，Flutter 中的界面都是以 Widget 表示的，因为 Flutter 中一切皆为 Widget。你使用 Navigator 在表示不同屏幕或页面，或者仅仅是相同数据的不同状态和渲染的各个 Route 之间进行导航。

As mentioned in the Intents section, screens in Flutter are represented by Widgets since everything is a widget in Flutter. Use a Navigator to move between different Routes that represent different screens or pages, or maybe just different states or renderings of the same data.

如何监听 Android Activity 的生命周期事件？

How do I listen to Android activity lifecycle events?

在 Android 中，你可以覆写 Actvity 的生命周期方法来监听其生命周期，也可以在 Application 上注册 ActivityLifecycleCallbacks。在 Flutter 中，这两种方法都没有，但是你可以通过绑定 WidgetsBinding 观察者并监听 didChangeAppLifecycleState() 的变化事件来监听生命周期。

In Android, you can override methods from the Activity to capture lifecycle methods for the activity itself, or register ActivityLifecycleCallbacks on the Application. In Flutter, you have neither concept, but you can instead listen to lifecycle events by hooking into the WidgetsBinding observer and listening to the didChangeAppLifecycleState() change event.

可以被观察的生命周期事件有：

The observable lifecycle events are:

inactive — 应用处于非活跃状态并且不接收用户输入。
inactive — The application is in an inactive state and is not receiving user input.
detached — 应用依然保留 flutter engine，但是它会脱离全部宿主 view。
detached — The application is still hosted on a flutter engine but is detached from any host views.
paused — 应用当前对用户不可见，无法响应用户输入，并运行在后台。这个事件对应于 Android 中的 onPause()；
paused — The application is not currently visible to the user, not responding to user input, and running in the background. This is equivalent to onPause() in Android.
resumed — 应用对用户可见并且可以响应用户的输入。这个事件对应于 Android 中的 onPostResume()；
suspending — 应用暂时被挂起。这个事件对应于 Android 中的 onStop； iOS 上由于没有对应的事件，因此不会触发此事件。
resumed — The application is visible and responding to user input. This is equivalent to onPostResume() in Android.

想要了解这些状态含义的更多细节，请查看 AppLifecycleStatus 文档。

For more details on the meaning of these states, see the AppLifecycleStatus documentation.

你可能已经注意到，只有一小部分的 Activity 生命周期事件是可用的；虽然 FlutterActivity 在内部捕获了几乎所有的 Activity 生命周期事件并将它们发送给 Flutter 引擎，但是它们大部分都向你屏蔽了。 Flutter 为你管理引擎的启动和停止，在大部分情况下几乎没有理由要在 Flutter 一端监听 Activity 的生命周期。如果你需要通过监听生命周期来获取或释放原生的资源，你无论如何都应该在原生一端做这件事。

As you might have noticed, only a small minority of the Activity lifecycle events are available; while FlutterActivity does capture almost all the activity lifecycle events internally and send them over to the Flutter engine, they’re mostly shielded away from you. Flutter takes care of starting and stopping the engine for you, and there is little reason for needing to observe the activity lifecycle on the Flutter side in most cases. If you need to observe the lifecycle to acquire or release any native resources, you should likely be doing it from the native side, at any rate.

下面的例子展示了如何监听容器 Activity 的生命周期状态：

Here’s an example of how to observe the lifecycle status of the containing activity:

import 'package:flutter/widgets.dart';

class LifecycleWatcher extends StatefulWidget {
  @override
  _LifecycleWatcherState createState() => _LifecycleWatcherState();
}

class _LifecycleWatcherState extends State<LifecycleWatcher> with WidgetsBindingObserver {
  AppLifecycleState _lastLifecycleState;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    setState(() {
      _lastLifecycleState = state;
    });
  }

  @override
  Widget build(BuildContext context) {
    if (_lastLifecycleState == null) {
      return Text(
        'This widget has not observed any lifecycle changes.',
        textDirection: TextDirection.ltr,
      );
    }

    return Text(
      'The most recent lifecycle state this widget observed was: $_lastLifecycleState.',
      textDirection: TextDirection.ltr,
    );
  }
}

void main() {
  runApp(Center(child: LifecycleWatcher()));
}

布局

Layouts

LinearLayout 的对应概念是什么？

What is the equivalent of a LinearLayout?

在 Android 中，LinearLayout 用于线性布局 widget 的—水平或者垂直。在 Flutter 中，使用 Row 或者 Column Widget 来实现相同的效果。

In Android, a LinearLayout is used to lay your widgets out linearly—either horizontally or vertically. In Flutter, use the Row or Column widgets to achieve the same result.

如果你注意看的话，会发现下面的两段代码除了 Row 和 Column widget 以外是一模一样的。它们的孩子是一样的，而这个特性可以被充分利用来开发包含有相同的孩子但是会随时间改变的复杂布局。

If you notice the two code samples are identical with the exception of the “Row” and “Column” widget. The children are the same and this feature can be exploited to develop rich layouts that can change overtime with the same children.

  @override
  Widget build(BuildContext context) {
    return Row(
      mainAxisAlignment: MainAxisAlignment.center,
      children: <Widget>[
        Text('Row One'),
        Text('Row Two'),
        Text('Row Three'),
        Text('Row Four'),
      ],
    );
  }

@override
Widget build(BuildContext context) {
  return Column(
    mainAxisAlignment: MainAxisAlignment.center,
    children: <Widget>[
      Text('Column One'),
      Text('Column Two'),
      Text('Column Three'),
      Text('Column Four'),
    ],
  );
}

如果想学习更多的构建线性布局的内容，请阅读社区贡献的 Medium 文章给 Android 开发者的 Flutter 指南：如何在 Flutter 中设计线性布局？

To learn more about building linear layouts, see the community-contributed Medium article Flutter for Android Developers: How to design LinearLayout in Flutter.

RelativeLayout 的对应概念是什么？

What is the equivalent of a RelativeLayout?

RelativeLayout 通过 Widget 的相互位置对它们进行布局。在 Flutter 中，有几种实现相同效果的方法。

A RelativeLayout lays your widgets out relative to each other. In Flutter, there are a few ways to achieve the same result.

你可以通过组合使用 Column、Row 和 Stack Widget 实现 RelativeLayout 的效果。你还可以在 Widget 构造器内声明孩子相对父亲的布局规则。

You can achieve the result of a RelativeLayout by using a combination of Column, Row, and Stack widgets. You can specify rules for the widgets constructors on how the children are laid out relative to the parent.

Collin 在 StackOverflow 上的回答是一个在 Flutter 中构建相对布局的好例子。

For a good example of building a RelativeLayout in Flutter, see Collin’s answer on StackOverflow.

ScrollView 的对应概念是什么？

What is the equivalent of a ScrollView?

在 Android 中，使用 ScrollView 布局 widget—如果用户的设备屏幕比应用的内容区域小，用户可以滑动内容。

In Android, use a ScrollView to lay out your widgets—if the user’s device has a smaller screen than your content, it scrolls.

在 Flutter 中，实现这个功能的最简单的方法是使用 ListView widget。从 Android 的角度看，这样做可能是杀鸡用牛刀了，但是 Flutter 中 ListView widget 既是一个 ScrollView，也是一个 Android 中的 ListView。

In Flutter, the easiest way to do this is using the ListView widget. This might seem like overkill coming from Android, but in Flutter a ListView widget is both a ScrollView and an Android ListView.

  @override
  Widget build(BuildContext context) {
    return ListView(
      children: <Widget>[
        Text('Row One'),
        Text('Row Two'),
        Text('Row Three'),
        Text('Row Four'),
      ],
    );
  }

在 Flutter 中如何处理屏幕旋转？

How do I handle landscape transitions in Flutter?

FlutterView 会处理配置的变化，前提条件是在 AndroidManifest.xml 文件中声明了：

FlutterView handles the config change if AndroidManifest.xml contains:

android:configChanges="orientation|screenSize"

手势监听和触摸事件处理

Gesture detection and touch event handling

How do I add an onClick listener to a widget in Flutter?

在 Android 中，你可以通过调用 setOnClickListener 方法在按钮这样的 View 上添加点击监听器。

In Android, you can attach onClick to views such as button by calling the method ‘setOnClickListener’.

在 Flutter 中有两种添加触摸监听器的方法：

In Flutter there are two ways of adding touch listeners:

如果 Widget 支持事件监听，那么向它传入一个方法并在方法中处理事件。例如，RaisedButton 有一个 onPressed 参数：
If the Widget supports event detection, pass a function to it and handle it in the function. For example, the ElevatedButton has an onPressed parameter:
```
@override
Widget build(BuildContext context) {
  return ElevatedButton(
    onPressed: () {
      print('click');
    },
    child: Text('Button'),
  );
}
```

如果 Widget 不支持事件监听，将 Widget 包装进一个 GestureDetector 中并向 onTap 参数传入一个方法。

If the Widget doesn’t support event detection, wrap the widget in a GestureDetector and pass a function to the onTap parameter.

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: GestureDetector(
          onTap: () {
            print('tap');
          },
          child: FlutterLogo(
            size: 200.0,
          ),
        ),
      ),
    );
  }
}

如何处理 Widget 上的其它手势？

How do I handle other gestures on widgets?

使用 GestureDetector 可以监听非常多的手势，例如：

Using the GestureDetector, you can listen to a wide range of Gestures such as:

Tap
- onTapDown - 一个可能产生点击事件的指针触摸到屏幕的特定位置。
  onTapDown - A pointer that might cause a tap has contacted the screen at a particular location.
- onTapUp - 一个产生了点击事件的指针停止触摸屏幕的特定位置。
  onTapUp - A pointer that triggers a tap has stopped contacting the screen at a particular location.
- onTap - 一个点击事件已经发生。
  onTap - A tap has occurred.
- onTapCancel - 之前触发了 onTapDown 事件的指针不会产生点击事件。
  onTapCancel - The pointer that previously triggered the onTapDown won’t cause a tap.
Double tap
- onDoubleTap - 用户在屏幕同一位置连续快速地点击两次。
  onDoubleTap - The user tapped the screen at the same location twice in quick succession.
Long press
- onLongPress - 指针在屏幕的同一位置保持了一段较长时间的触摸状态。
  onLongPress - A pointer has remained in contact with the screen at the same location for a long period of time.
Vertical drag
- onVerticalDragStart - 指针已经触摸屏幕并可能开始垂直移动。
  onVerticalDragStart - A pointer has contacted the screen and might begin to move vertically.
- onVerticalDragUpdate - 触摸屏幕的指针在垂直方向移动了更多的距离。
  onVerticalDragUpdate - A pointer in contact with the screen has moved further in the vertical direction.
- onVerticalDragEnd - 之前和屏幕接触并垂直移动的指针不再继续和屏幕接触，并且在和屏幕停止接触的时候以一定的速度移动。
  onVerticalDragEnd - A pointer that was previously in contact with the screen and moving vertically is no longer in contact with the screen and was moving at a specific velocity when it stopped contacting the screen.
Horizontal drag
- onHorizontalDragStart - 指针已经触摸屏幕并可能开始水平移动。
  onHorizontalDragStart - A pointer has contacted the screen and might begin to move horizontally.
- onHorizontalDragUpdate - 触摸屏幕的指针在水平方向移动了更多的距离。
  onHorizontalDragUpdate - A pointer in contact with the screen has moved further in the horizontal direction.
- onHorizontalDragEnd - 之前和屏幕接触并水平移动的指针不再继续和屏幕接触，并且在和屏幕停止接触的时候以一定的速度移动。
  onHorizontalDragEnd - A pointer that was previously in contact with the screen and moving horizontally is no longer in contact with the screen and was moving at a specific velocity when it stopped contacting the screen.

下面的例子展示了一个实现了双击旋转 Flutter 标志的 GestureDetector：

The following example shows a GestureDetector that rotates the Flutter logo on a double tap:

AnimationController controller;
CurvedAnimation curve;

class SampleApp extends StatefulWidget {
  @override
  _SampleAppState createState() => _SampleAppState();
}

class _SampleAppState extends State<SampleApp> with SingleTickerProviderStateMixin {
  @override
  void initState() {
    super.initState();
    controller = AnimationController(
      vsync: this,
      duration: const Duration(milliseconds: 2000),
    );
    curve = CurvedAnimation(
      parent: controller,
      curve: Curves.easeIn,
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: GestureDetector(
          onDoubleTap: () {
            if (controller.isCompleted) {
              controller.reverse();
            } else {
              controller.forward();
            }
          },
          child: RotationTransition(
            turns: curve,
            child: FlutterLogo(
              size: 200.0,
            ),
          ),
        ),
      ),
    );
  }
}

Listviews 和 adapters

Listviews & adapters

ListView 在 Flutter 中的对应概念是什么？

What is the alternative to a ListView in Flutter?

Flutter 中 ListView 的对应概念仍然是…ListView！

The equivalent to a ListView in Flutter is … a ListView!

使用 Android 的 ListView 时，创建一个 adapter 并将其传给 ListView， ListView 渲染 adapter 返回的每一行内容。然后，你需要确保回收了每一行视图，否则，你会遇到各种奇怪的界面和内存问题。

In an Android ListView, you create an adapter and pass it into the ListView, which renders each row with what your adapter returns. However, you have to make sure you recycle your rows, otherwise, you get all sorts of crazy visual glitches and memory issues.

因为 Flutter widget 不可变的特点，你需要向 ListView 传入一组 widget， Flutter 会保证滑动的快速顺畅。

Due to Flutter’s immutable widget pattern, you pass a list of widgets to your ListView, and Flutter takes care of making sure that scrolling is fast and smooth.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: ListView(children: _getListData()),
    );
  }

  List<Widget> _getListData() {
    List<Widget> widgets = [];
    for (int i = 0; i < 100; i++) {
      widgets.add(Padding(
        padding: EdgeInsets.all(10.0),
        child: Text('Row $i'),
      ));
    }
    return widgets;
  }
}

如何知道点击了哪个列表项？

How do I know which list item is clicked on?

在 Android 中，ListView 有一个可以帮助你定位哪个列表项被点击了的方法 onItemClickListener。在 Flutter 中，则使用传入 widget 的触摸监听。

In Android, the ListView has a method to find out which item was clicked ‘onItemClickListener’. In Flutter, use the touch handling provided by the passed-in widgets.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: ListView(children: _getListData()),
    );
  }

  List<Widget> _getListData() {
    List<Widget> widgets = [];
    for (int i = 0; i < 100; i++) {
      widgets.add(
        GestureDetector(
          onTap: () {
            print('row tapped');
          },
          child: Padding(
            padding: EdgeInsets.all(10.0),
            child: Text('Row $i'),
          ),
        ),
      );
    }
    return widgets;
  }
}

如何动态更新 ListView？

How do I update ListView’s dynamically?

在 Android 中，你需要更新 adapter 并调用 notifyDataSetChanged。

On Android, you update the adapter and call notifyDataSetChanged.

在 Flutter 中，如果你准备在 setState() 里更新一组 widget，你很快会发现你的数据并没有更新到界面上。这是因为当 setState() 被调用的时候， Flutter 渲染引擎会查看 Widget 树是否有任何更改。当引擎检查到 ListView，他会执行 == 检查，并判断两个 ListView 是一样的。没有任何更改，所以也就不需要更新。

In Flutter, if you were to update the list of widgets inside a setState(), you would quickly see that your data did not change visually. This is because when setState() is called, the Flutter rendering engine looks at the widget tree to see if anything has changed. When it gets to your ListView, it performs a == check, and determines that the two ListViews are the same. Nothing has changed, so no update is required.

更新 ListView 的一个简单方法是，在 setState() 里创建一个新的 List，并将数据从旧列表拷贝到新列表。虽然这个方法很简单，就如下面例子所示，但是并不推荐在大数据集的时候使用。

For a simple way to update your ListView, create a new List inside of setState(), and copy the data from the old list to the new list. While this approach is simple, it is not recommended for large data sets, as shown in the next example.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List<Widget> widgets = [];

  @override
  void initState() {
    super.initState();
    for (int i = 0; i < 100; i++) {
      widgets.add(getRow(i));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: ListView(children: widgets),
    );
  }

  Widget getRow(int i) {
    return GestureDetector(
      onTap: () {
        setState(() {
          widgets = List.from(widgets);
          widgets.add(getRow(widgets.length));
          print('row $i');
        });
      },
      child: Padding(
        padding: EdgeInsets.all(10.0),
        child: Text('Row $i'),
      ),
    );
  }
}

推荐的高效且有效的创建一个列表的方法是使用 ListView.Builder。这个方法非常适用于动态列表或者拥有大量数据的列表。这基本上就是 Android 里的 RecyclerView，会为你自动回收列表项：

The recommended, efficient, and effective way to build a list uses a ListView.Builder. This method is great when you have a dynamic List or a List with very large amounts of data. This is essentially the equivalent of RecyclerView on Android, which automatically recycles list elements for you:

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List<Widget> widgets = [];

  @override
  void initState() {
    super.initState();
    for (int i = 0; i < 100; i++) {
      widgets.add(getRow(i));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: ListView.builder(
        itemCount: widgets.length,
        itemBuilder: (BuildContext context, int position) {
          return getRow(position);
        },
      ),
    );
  }

  Widget getRow(int i) {
    return GestureDetector(
      onTap: () {
        setState(() {
          widgets.add(getRow(widgets.length));
          print('row $i');
        });
      },
      child: Padding(
        padding: EdgeInsets.all(10.0),
        child: Text('Row $i'),
      ),
    );
  }
}

不用创建一个 “ListView”，而是创建接收两个参数的 ListView.Builder，两个参数分别是列表的初始长度和一个 ItemBuilder 方法。

Instead of creating a “ListView”, create a ListView.builder that takes two key parameters: the initial length of the list, and an ItemBuilder function.

ItemBuilder 方法和 Android adapter 里的 getView 方法类似；它通过位置返回你期望在这个位置渲染的列表项。

The ItemBuilder function is similar to the getView function in an Android adapter; it takes a position, and returns the row you want rendered at that position.

最后也是最重要的一条，需要注意 onTap() 方法不再重建列表项，但是会执行 .add 操作。

Finally, but most importantly, notice that the onTap() function doesn’t recreate the list anymore, but instead .adds to it.

文字处理

Working with text

如何为 Text Widget 设置自定义字体？

How do I set custom fonts on my Text widgets?

在 Android SDK 中（从 Android O 开始），你可以创建一个字体资源文件并将其传给 TextView 的 FontFamily 参数。

In Android SDK (as of Android O), you create a Font resource file and pass it into the FontFamily param for your TextView.

在 Flutter 中，将字体文件放入一个文件夹，并在 pubspec.yaml 文件中引用它，就和导入图片一样。

In Flutter, place the font file in a folder and reference it in the pubspec.yaml file, similar to how you import images.

fonts:
   - family: MyCustomFont
     fonts:
       - asset: fonts/MyCustomFont.ttf
       - style: italic

然后将字体赋值给你的 Text Widget：

Then assign the font to your Text widget:

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(
      title: Text('Sample App'),
    ),
    body: Center(
      child: Text(
        'This is a custom font text',
        style: TextStyle(fontFamily: 'MyCustomFont'),
      ),
    ),
  );
}

如何更改 Text Widget 的样式？

How do I style my Text widgets?

除了字体，你还可以自定义 Text Widget 的其它样式元素。Text Widget 的样式参数接收一个 TextStyle 对象，你可以在这个对象里自定义很多参数，例如：

Along with fonts, you can customize other styling elements on a Text widget. The style parameter of a Text widget takes a TextStyle object, where you can customize many parameters, such as:

color
decoration
decorationColor
decorationStyle
fontFamily
fontSize
fontStyle
fontWeight
hashCode
height
inherit
letterSpacing
textBaseline
wordSpacing

表单输入

Form input

如果需要更多使用表单的信息，请查看 Flutter Cookbook 中的检索一个文本字段的值。

For more information on using Forms, see Retrieve the value of a text field, from the Flutter Cookbook.

Input 的“提示” (hint) 的对应概念是什么？

What is the equivalent of a “hint” on an Input?

在 Flutter 中，你可以简单地通过向 Text Widget 构造器的 decoration 参数传入一个 InputDecoration 对象来为输入框展示一个“提示”或占位文本。

In Flutter, you can easily show a “hint” or a placeholder text for your input by adding an InputDecoration object to the decoration constructor parameter for the Text Widget.

body: Center(
  child: TextField(
    decoration: InputDecoration(hintText: 'This is a hint'),
  )
)

如何显示验证错误的信息？

How do I show validation errors?

就像上面实现“提示”功能一样，像 Text Widget 构造方法的 decoration 参数传入一个 InputDecoration 对象。

Just as you would with a “hint”, pass an InputDecoration object to the decoration constructor for the Text widget.

然而，你并不想一开始就显示错误信息。相反，当用户输入了无效的信息后，更新状态并传入一个新的 InputDecoration 对象。

However, you don’t want to start off by showing an error. Instead, when the user has entered invalid data, update the state, and pass a new InputDecoration object.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key? key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  String _errorText;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sample App'),
      ),
      body: Center(
        child: TextField(
          onSubmitted: (String text) {
            setState(() {
              if (!isEmail(text)) {
                _errorText = 'Error: This is not an email';
              } else {
                _errorText = null;
              }
            });
          },
          decoration: InputDecoration(
            hintText: 'This is a hint',
            errorText: _getErrorText(),
          ),
        ),
      ),
    );
  }

  String _getErrorText() {
    return _errorText;
  }

  bool isEmail(String em) {
    String emailRegexp =
        r'^(([^<>()[\]\\.,;:\s@\"]+(\.[^<>()[\]\\.,;:\s@\"]+)*)|(\".+\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$';

    RegExp regExp = RegExp(emailRegexp);

    return regExp.hasMatch(em);
  }
}

Flutter 插件

Flutter plugins

如何使用 GPS 传感器？

How do I access the GPS sensor?

使用 geolocator 社区插件。

Use the geolocator community plugin.

如何使用相机？

How do I access the camera?

image_picker 插件被常用于相机功能的使用。

The image_picker plugin is popular for accessing the camera.

如何使用 Facebook 登录？

How do I log in with Facebook?

使用 flutter_facebook_login 社区插件实现 Facebook 登录功能。

To Log in with Facebook, use the flutter_facebook_login community plugin.

如何使用 Firebase 的功能？

How do I use Firebase features?

官方插件提供了 Firebase 的大多数功能。这些插件都是由 Flutter 团队维护的官方集成插件：

Most Firebase functions are covered by first party plugins. These plugins are first-party integrations, maintained by the Flutter team:

firebase_admob 提供 Firebase AdMob 功能
firebase_admob for Firebase AdMob
firebase_analytics 提供 Firebase Analytics 功能
firebase_analytics for Firebase Analytics
firebase_auth 提供 Firebase Auth 功能
firebase_auth for Firebase Auth
firebase_database 提供 Firebase RTDB 功能
firebase_database for Firebase RTDB
firebase_storage 提供 Firebase Cloud Storage 功能
firebase_storage for Firebase Cloud Storage
firebase_messaging 提供 Firebase Messaging (FCM) 功能
firebase_messaging for Firebase Messaging (FCM)
flutter_firebase_ui 提供快速的 Firebase Auth 集成功能 (Facebook, Google, Twitter 和 email)
flutter_firebase_ui for quick Firebase Auth integrations (Facebook, Google, Twitter and email)
cloud_firestore 提供 Firebase Cloud Firestore 功能
cloud_firestore for Firebase Cloud Firestore

你可以在 Pub 网站上查找一些官方插件没有直接支持的功能的第三方 Firebase 插件。

You can also find some third-party Firebase plugins on Pub that cover areas not directly covered by the first-party plugins.

如何创建自己的自定义原生集成插件？

How do I build my own custom native integrations?

如果有 Flutter 官方或社区第三方插件没有涵盖的平台特定的功能，你可以根据开发包和插件页面创建自己的插件。

If there is platform-specific functionality that Flutter or its community Plugins are missing, you can build your own following the developing packages and plugins page.

Flutter 的插件架构，简而言之，和 Android 中的事件总线的使用非常相似：你发送一个消息，并让接受者处理并返回一个结果给你。在这种情况下，接受者是运行在 Android 或 iOS 原生端的代码。

Flutter’s plugin architecture, in a nutshell, is much like using an Event bus in Android: you fire off a message and let the receiver process and emit a result back to you. In this case, the receiver is code running on the native side on Android or iOS.

如何在 Flutter 应用中使用 NDK？

How do I use the NDK in my Flutter application?

如果你在现有的 Android 应用中使用 NDK，并且希望你的 Flutter 应用可以利用你的 native 库，这可以通过创建一个自定义插件实现。

If you use the NDK in your current Android application and want your Flutter application to take advantage of your native libraries then it’s possible by building a custom plugin.

你的自定义插件首先和你的 Android 应用通信，Android 应用会通过 JNI 调用 native 方法。一旦有返回值，就可以向 Flutter 发送回一个消息并渲染结果。

Your custom plugin first talks to your Android app, where you call your native functions over JNI. Once a response is ready, send a message back to Flutter and render the result.

暂时还不支持从 Flutter 中直接调用 native 代码。

Calling native code directly from Flutter is currently not supported.

主题(Themes)

Themes

如何对应用使用主题？

How do I theme my app?

Flutter 提供开箱即用的优美的 Material Design 实现，可以满足你通常需要的各种样式和主题的需求。不同于 Android 中你在 XML 文件中定义主题并在 AndroidManifest.xml 中将其赋值给你的应用， Flutter 中是在顶层 Widget 上声明主题。

Out of the box, Flutter comes with a beautiful implementation of Material Design, which takes care of a lot of styling and theming needs that you would typically do. Unlike Android where you declare themes in XML and then assign it to your application using AndroidManifest.xml, in Flutter you declare themes in the top level widget.

为了在应用中利用好 Material 组件，你可以在应用中声明一个顶层 Widget MeterialApp 作为入口。 MaterialApp 是一个包装了一系列 Widget 的为你给予便利的 Widget，而这些 Widget 通常是实现 Material Design 的应用所必须的。它基于 WidgetsApp 并添加了 Material 相关的功能。

To take full advantage of Material Components in your app, you can declare a top level widget MaterialApp as the entry point to your application. MaterialApp is a convenience widget that wraps a number of widgets that are commonly required for applications implementing Material Design. It builds upon a WidgetsApp by adding Material specific functionality.

你也可以使用 WidgetApp 作为应用的 Widget，它会提供一些相同的功能，但是不如 MaterialApp 提供的功能丰富。

You can also use a WidgetsApp as your app widget, which provides some of the same functionality, but is not as rich as MaterialApp.

如果要自定义任意子组件的颜色或者样式，给 MaterialApp Widget 传入一个 ThemeData 对象即可。例如，在下面的代码中，主色调设置为蓝色，文本选中颜色设置为红色。

To customize the colors and styles of any child components, pass a ThemeData object to the MaterialApp widget. For example, in the code below, the primary swatch is set to blue and text selection color is red.

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
        textSelectionTheme: TextSelectionThemeData(selectionColor: Colors.red),
      ),
      home: SampleAppPage(),
    );
  }
}

数据库和本地存储

Databases and local storage

如何使用 Shared Preferences？

How do I access Shared Preferences?

在 Android 中，你可以使用 SharedPreferences API 来存储少量的键值对。

In Android, you can store a small collection of key-value pairs using the SharedPreferences API.

在 Flutter 中，使用 Shared_Preferences 插件实现此功能。这个插件同时包装了 Shared Preferences 和 NSUserDefaults（iOS 平台对应 API）的功能。

In Flutter, access this functionality using the Shared_Preferences plugin. This plugin wraps the functionality of both Shared Preferences and NSUserDefaults (the iOS equivalent).

import 'package:flutter/material.dart';

import 'package:shared_preferences/shared_preferences.dart';

void main() {
  runApp(
    MaterialApp(
      home: Scaffold(
        body: Center(
          child: ElevatedButton(
            onPressed: _incrementCounter,
            child: Text('Increment Counter'),
          ),
        ),
      ),
    ),
  );
}

void _incrementCounter() async {
  SharedPreferences prefs = await SharedPreferences.getInstance();
  int counter = (prefs.getInt('counter') ?? 0) + 1;
  print('Pressed $counter times.');
  prefs.setInt('counter', counter);
}

在 Flutter 中如何使用 SQLite？

How do I access SQLite in Flutter?

在 Android 中，你会使用 SQLite 来存储可以通过 SQL 进行查询的结构化数据。

In Android, you use SQLite to store structured data that you can query using SQL.

在 Flutter 中，使用 SQFlite 插件实现此功能。

In Flutter, access this functionality using the SQFlite plugin.

Debugging

应该使用什么工具调试我的 Flutter 应用？

What tools can I use to debug my app in Flutter?

请使用开发者工具 debug 你的 Flutter 和 Dart 应用。

Use the DevTools suite for debugging Flutter or Dart apps.

开发者工具包含了 profiling 构建、检查堆栈、检视 widget 树、诊断信息记录、调试、执行代码行观察、调试内存泄漏和内存碎片等。有关更多信息，请参阅开发者工具文档。

DevTools includes support for profiling, examining the heap, inspecting the widget tree, logging diagnostics, debugging, observing executed lines of code, debugging memory leaks and memory fragmentation. For more information, see the DevTools documentation.

通知

Notifications

如何设置推送通知？

How do I set up push notifications?

在 Android 中，你可以使用 Firebase Cloud Messaging 来为应用设置推送通知。

In Android, you use Firebase Cloud Messaging to setup push notifications for your app.

在 Flutter 中，则使用 Firebase Messaging 插件实现此功能。想要获得更多关于使用 Firebase Cloud Messaging API 的信息，请查阅 firebase_messaging 插件文档。

In Flutter, access this functionality using the Firebase Messaging plugin. For more information on using the Firebase Cloud Messaging API, see the firebase_messaging plugin documentation.

给 iOS 开发者的 Flutter 指南

视图
Views
导航
Navigation
线程和异步
Threading & asynchronicity
工程结构，本地化，依赖和资源
Project structure, localization, dependencies and assets
ViewControllers
- ViewControllers 相当于 Flutter 中的什么？
  What is the equivalent to ViewController in Flutter?
- 如何监听 iOS 中的生命周期？
  How do I listen to iOS lifecycle events?
布局
Layouts
手势检测与 touch 事件处理
Gesture detection and touch event handling
- 如何给 Flutter 的 widget 添加点击事件？
  How do I add a click listener to a widget in Flutter?
- 如何处理 widget 的其他手势？
  How do I handle other gestures on widgets?
主题和文字
Theming and text
表单输入
Form input
和硬件、第三方服务以及系统平台交互
Interacting with hardware, third party services and the platform
数据库和本地存储
Databases and local storage
- Flutter 中如何访问 UserDefaults？
  How do I access UserDefault in Flutter?
- CoreData 相当于 Flutter 中的什么？
  What is the equivalent to CoreData in Flutter?
Debugging
- 应该使用什么工具调试我的 Flutter 应用？
  What tools can I use to debug my app in Flutter?
通知
Notifications
- 如何设置推送通知？
  How do I set up push notifications?

这篇文章是为那些想将已有的 iOS 开发经验运用到 Flutter 开发中的 iOS 开发者所作。如果你理解 iOS framework 的基本原理，那么你可以将这篇文章作为学习 Flutter 开发的起点。

This document is for iOS developers looking to apply their existing iOS knowledge to build mobile apps with Flutter. If you understand the fundamentals of the iOS framework then you can use this document as a way to get started learning Flutter development.

在开始本文档之前，建议先浏览一下这个 15 分钟的视频，了解一下 Cupertino package 是什么吧：

Before diving into this doc, you might want to watch a 15-minute video from the Flutter Youtube channel about the Cupertino package.

你的 iOS 开发技能对于开发 Flutter 而言非常宝贵，因为 Flutter 也依赖操作系统进行众多功能和配置。 Flutter 是一种全新的构建移动应用的方式，同时它也包含了可以与 iOS（和 Android）进行非 UI 通信的插件系统。如果你已经是 iOS 开发专家，那么你并不需要重新学习 Flutter 的所有内容。

Your iOS knowledge and skill set are highly valuable when building with Flutter, because Flutter relies on the mobile operating system for numerous capabilities and configurations. Flutter is a new way to build UIs for mobile, but it has a plugin system to communicate with iOS (and Android) for non-UI tasks. If you’re an expert in iOS development, you don’t have to relearn everything to use Flutter.

Flutter 早已对在 iOS 上运行 Flutter 框架作了许多优化。若你需要查看相关内容，请阅读平台适配。

Flutter also already makes a number of adaptations in the framework for you when running on iOS. For a list, see Platform adaptations.

你同样可以将这篇文章当作一份手册查看，以便查找并解决你所遇到的问题。

This document can be used as a cookbook by jumping around and finding questions that are most relevant to your needs.

视图

Views

`UIView` 相当于 Flutter 中的什么？

What is the equivalent of a UIView in Flutter?

在 iOS 中，你在 UI 中创建的大部分视图都是 UIView 的实例。而在构造布局时，这些视图也可以作为其他视图的容器。

On iOS, most of what you create in the UI is done using view objects, which are instances of the UIView class. These can act as containers for other UIView classes, which form your layout.

在 Flutter 中，同 UIView 能够进行类比的就是 Widget 了。但 Widget 和 iOS 里的视图并不能同等对待，不过当你想要了解 Flutter 的工作原理时，你可以把它理解为“声明和构造 UI 的方法”。

In Flutter, the rough equivalent to a UIView is a Widget. Widgets don’t map exactly to iOS views, but while you’re getting acquainted with how Flutter works you can think of them as “the way you declare and construct UI”.

然而，Widget 和 UIView 还是有着相当一部分区别的。首先，widget 拥有着不同的生命周期：整个生命周期内它是不可变的，且只能够存活到被修改的时候。一旦 widget 实例或者它的状态发生了改变， Flutter 框架就会创建一个新的由 Widget 实例构造而成的树状结构。而在 iOS 里，修改一个视图并不会导致它重新创建实例，它作为一个可变对象，只会绘制一次，只有在发生 setNeedsDisplay() 调用之后才会发生重绘。

However, these have a few differences to a UIView. To start, widgets have a different lifespan: they are immutable and only exist until they need to be changed. Whenever widgets or their state change, Flutter’s framework creates a new tree of widget instances. In comparison, an iOS view is not recreated when it changes, but rather it’s a mutable entity that is drawn once and doesn’t redraw until it is invalidated using setNeedsDisplay().

还有，和 UIView 不同，Flutter 的 widget 是很轻量的，一部分原因就是源于它的不可变特性。因为它并不是视图，也不直接绘制任何内容，而是作为对 UI 及其特性的一种描述，而被“注入”到视图中去。

Furthermore, unlike UIView, Flutter’s widgets are lightweight, in part due to their immutability. Because they aren’t views themselves, and aren’t directly drawing anything, but rather are a description of the UI and its semantics that get “inflated” into actual view objects under the hood.

Flutter 包含了 Material Components 库。内容都是一些遵循了 Material Design 设计规范的组件。 Material Design 是一种灵活的支持全平台的设计体系，其中也包括了 iOS。

但是 Flutter 的灵活性和表现力使其能够适配任何的设计语言。在 iOS 中，你可以通过 Cupertino widgets 来构造类似于 Apple iOS 设计语言的接口。

But Flutter is flexible and expressive enough to implement any design language. On iOS, you can use the Cupertino widgets to produce an interface that looks like Apple’s iOS design language.

我该如何更新 widget？

How do I update widgets?

在 iOS 可以直接对视图进行修改。但是在 Flutter 中，widget 都是不可变的，所以也不能够直接对其修改。所以，你必须通过修改 widget 的 state 来达到更新视图的目的。

To update your views on iOS, you directly mutate them. In Flutter, widgets are immutable and not updated directly. Instead, you have to manipulate the widget’s state.

于是，就引入了 Stateful widget 和 Stateless widget 的概念。和字面意思相同，StatelessWidget 就是一个没有绑定状态的 widget。

This is where the concept of Stateful vs Stateless widgets comes in. A StatelessWidget is just what it sounds like—a widget with no state attached.

当某个 widget 不需要依赖任何别的初始配置来对这个 widget 进行描述时， StatelessWidgets 会是很有用的。

StatelessWidgets are useful when the part of the user interface you are describing does not depend on anything other than the initial configuration information in the widget.

举个例子，在 iOS 中，你需要把 logo 当作 image 并将它放置在 UIImageView 中，如果在运行时这个 logo 不会发生变化，那么对应 Flutter 中你应该使用 StatelessWidget。

For example, in iOS, this is similar to placing a UIImageView with your logo as the image. If the logo is not changing during runtime, use a StatelessWidget in Flutter.

但是如果你想要根据 HTTP 请求的返回结果动态的修改 UI，那么你应该使用 StatefulWidget。在 HTTP 请求结束后，通知 Flutter 更新这个 widget 的 State，然后 UI 就会得到更新。

If you want to dynamically change the UI based on data received after making an HTTP call, use a StatefulWidget. After the HTTP call has completed, tell the Flutter framework that the widget’s State is updated, so it can update the UI.

StatefulWidget 和 StatelessWidget 最重要的区别就是， StatefulWidget 中有一个 State 对象，它用来存储一些状态的信息，并在整个生命周期内保持不变。

The important difference between stateless and stateful widgets is that StatefulWidgets have a State object that stores state data and carries it over across tree rebuilds, so it’s not lost.

如果你对此还存有疑虑，记住一点：如果一个 widget 在 build 方法之外（比如运行时下发生用户点击事件）被修改，那么就应该是有状态的。如果一个 widget 一旦生成就不再发生改变，那么它就是无状态的。然而，即使一个 widget 是有状态的，如果不是自身直接响应修改（或别的输入），那么他的父容器也可以是无状态的。

If you are in doubt, remember this rule: if a widget changes outside of the build method (because of runtime user interactions, for example), it’s stateful. If the widget never changes, once built, it’s stateless. However, even if a widget is stateful, the containing parent widget can still be stateless if it isn’t itself reacting to those changes (or other inputs).

下面是如何使用 StatelessWidget 的示例。Text 是一个常用的 StatelessWidget。如果你看了 Text 的源代码，就会发现它继承于 StatelessWidget。

The following example shows how to use a StatelessWidget. A common StatelessWidget is the Text widget. If you look at the implementation of the Text widget you’ll find it subclasses StatelessWidget.

Text(
  'I like Flutter!',
  style: TextStyle(fontWeight: FontWeight.bold),
);

看了上面的代码，你会注意到 Text 没有携带任何状态，它只会渲染初始化时传进来的内容。

If you look at the code above, you might notice that the Text widget carries no explicit state with it. It renders what is passed in its constructors and nothing more.

然而，如果你想要动态地修改文本为 “I Like Flutter”，比如说在点击一个 FloatingActionButton 时该怎么做呢？

But, what if you want to make “I Like Flutter” change dynamically, for example when clicking a FloatingActionButton?

想要实现这个需求，只需要把 Text 放到 StatefulWidget 中，并在用户点击按钮时更新它即可。

To achieve this, wrap the Text widget in a StatefulWidget and update it when the user clicks the button.

下面是示例代码：

For example:

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  // Default placeholder text
  String textToShow = "I Like Flutter";
  void _updateText() {
    setState(() {
      // update the text
      textToShow = "Flutter is Awesome!";
    });
  }
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: Center(child: Text(textToShow)),
      floatingActionButton: FloatingActionButton(
        onPressed: _updateText,
        tooltip: 'Update Text',
        child: Icon(Icons.update),
      ),
    );
  }
}

如何对 widget 做布局？Storyboard 哪去了？

How do I lay out my widgets? Where is my Storyboard?

在 iOS 开发中，你可能会经常使用 Storyboard 来组织你的视图，并直接通过 Storyboard 或者在 ViewController 中通过代码来设置约束。而在 Flutter 中，你要通过代码来对 widget 进行组织来形成一个 widget 树状结构。

In iOS, you might use a Storyboard file to organize your views and set constraints, or you might set your constraints programmatically in your view controllers. In Flutter, declare your layout in code by composing a widget tree.

下面的例子展示了如何展示一个带有 padding 的 widget：

The following example shows how to display a simple widget with padding:

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(
      title: Text("Sample App"),
    ),
    body: Center(
      child: CupertinoButton(
        onPressed: () {
          setState(() { _pressedCount += 1; });
        },
        child: Text('Hello'),
        padding: EdgeInsets.only(left: 10.0, right: 10.0),
      ),
    ),
  );
}

你可以为任何 widget 添加 padding，来达到类似在 iOS 中视图约束的作用。

You can add padding to any widget, which mimics the functionality of constraints in iOS.

你可以在 widget 目录中查看 Flutter 提供的所有 widget 布局方法。

You can view the layouts that Flutter has to offer in the widget catalog.

如何增加或者移除一个组件？

How do I add or remove a component from my layout?

在 iOS 中，你可以通过调用父视图的 addSubview() 方法或者 removeFromSuperview() 方法来动态的添加或移除视图。在 Flutter 中，因为 widget 是不可变的，所以没有提供直接同 addSubview() 作用相同的方法。但是你可以通过向父视图传递一个返回值是 widget 的方法，并通过一个 boolean flag 来控制子视图的存在。

In iOS, you call addSubview() on the parent, or removeFromSuperview() on a child view to dynamically add or remove child views. In Flutter, because widgets are immutable there is no direct equivalent to addSubview(). Instead, you can pass a function to the parent that returns a widget, and control that child’s creation with a boolean flag.

下面的例子中像你展示了如何让用户通过点击 FloatingActionButton 按钮来达到在两个 widget 中切换的目的。

The following example shows how to toggle between two widgets when the user clicks the FloatingActionButton:

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  // Default value for toggle
  bool toggle = true;
  void _toggle() {
    setState(() {
      toggle = !toggle;
    });
  }

  _getToggleChild() {
    if (toggle) {
      return Text('Toggle One');
    } else {
      return CupertinoButton(
        onPressed: () {},
        child: Text('Toggle Two'),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: Center(
        child: _getToggleChild(),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _toggle,
        tooltip: 'Update Text',
        child: Icon(Icons.update),
      ),
    );
  }
}

How do I animate a widget?

在 iOS 里，你可以使用调用视图的 animate(withDuration:animations:) 方法来创建动画。在 Flutter 里，通过使用动画库将 widget 封装到 animated widget 中来实现带动画效果。

In iOS, you create an animation by calling the animate(withDuration:animations:) method on a view. In Flutter, use the animation library to wrap widgets inside an animated widget.

在 Flutter 里，使用 AnimationController，它是一个可以暂停、查找、停止和反转动画的 Animation<double> 类型。它需要一个 Ticker，在屏幕刷新时发出信号量，并在运行时对每一帧都产生一个 0~1 的线性差值。然后你可以创建一个或多个 Animation，并把它们添加到控制器中。

In Flutter, use an AnimationController, which is an Animation<double> that can pause, seek, stop, and reverse the animation. It requires a Ticker that signals when vsync happens and produces a linear interpolation between 0 and 1 on each frame while it’s running. You then create one or more Animations and attach them to the controller.

比如，你可以使用 CurvedAnimation 来实现一个曲线翻页动画。这种情况下，控制器就是动画进度的主要数据源，而 CurvedAnimation 计算曲线并替换控制器的默认线性运动，和 widget 一样，在 Flutter 里动画也可以复合嵌套。

当构建一个 widget 树时，可以将 Animation 赋值给 widget 用户表现动画能力的属性，比如 FadeTransition 的 opacity 属性，然后告诉控制器启动动画。

When building the widget tree you assign the Animation to an animated property of a widget, such as the opacity of a FadeTransition, and tell the controller to start the animation.

下面的示例描述了当你点击 FloatingActionButton 时，如何实现一个视图渐淡出成 logo 的 FadeTransition 效果。

The following example shows how to write a FadeTransition that fades the widget into a logo when you press the FloatingActionButton:

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Fade Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyFadeTest(title: 'Fade Demo'),
    );
  }
}

class MyFadeTest extends StatefulWidget {
  MyFadeTest({Key key, this.title}) : super(key: key);

  final String title;

  @override
  _MyFadeTest createState() => _MyFadeTest();
}

class _MyFadeTest extends State<MyFadeTest> with TickerProviderStateMixin {
  AnimationController controller;
  CurvedAnimation curve;

  @override
  void initState() {
    super.initState();
    controller = AnimationController(duration: const Duration(milliseconds: 2000), vsync: this);
    curve = CurvedAnimation(parent: controller, curve: Curves.easeIn);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Container(
          child: FadeTransition(
            opacity: curve,
            child: FlutterLogo(
              size: 100.0,
            )
          )
        )
      ),
      floatingActionButton: FloatingActionButton(
        tooltip: 'Fade',
        child: Icon(Icons.brush),
        onPressed: () {
          controller.forward();
        },
      ),
    );
  }

  @override
  dispose() {
    controller.dispose();
    super.dispose();
  }
}

关于更多的内容，可以查看 Animation 和 Motion widgets， Animations 教程，以及 Animations 概览。

For more information, see Animation & Motion widgets, the Animations tutorial, and the Animations overview.

如何渲染到屏幕上？

How do I draw to the screen?

在 iOS 里，可以使用 CoreGraphics 绘制线条和图形到屏幕上。 Flutter 里有一套基于 Cavans 实现的 API，有两个类可以帮助你进行绘制： CustomPaint 和 CustomPainter，后者实现了绘制图形到 canvas 的算法。

On iOS, you use CoreGraphics to draw lines and shapes to the screen. Flutter has a different API based on the Canvas class, with two other classes that help you draw: CustomPaint and CustomPainter, the latter of which implements your algorithm to draw to the canvas.

想要学习在 Flutter 里如何实现一个画笔，可以查看 Collin 在 StackOverflow 里的回答。

To learn how to implement a signature painter in Flutter, see Collin’s answer on StackOverflow.

import 'package:flutter/material.dart';

void main() => runApp(MaterialApp(home: DemoApp()));

class DemoApp extends StatelessWidget {
  Widget build(BuildContext context) => Scaffold(body: Signature());
}

class Signature extends StatefulWidget {
  SignatureState createState() => SignatureState();
}

class SignatureState extends State<Signature> {
  List<Offset> _points = <Offset>[];
  Widget build(BuildContext context) {
    return GestureDetector(
      onPanUpdate: (DragUpdateDetails details) {
        setState(() {
          RenderBox referenceBox = context.findRenderObject();
          Offset localPosition =
              referenceBox.globalToLocal(details.globalPosition);
          _points = List.from(_points)..add(localPosition);
        });
      },
      onPanEnd: (DragEndDetails details) => _points.add(null),
      child: CustomPaint(
        painter: SignaturePainter(_points),
        size: Size.infinite,
      ),
    );
  }
}

class SignaturePainter extends CustomPainter {
  SignaturePainter(this.points);
  final List<Offset> points;
  void paint(Canvas canvas, Size size) {
    var paint = Paint()
      ..color = Colors.black
      ..strokeCap = StrokeCap.round
      ..strokeWidth = 5.0;
    for (int i = 0; i < points.length - 1; i++) {
      if (points[i] != null && points[i + 1] != null)
        canvas.drawLine(points[i], points[i + 1], paint);
    }
  }

  bool shouldRepaint(SignaturePainter other) => other.points != points;
}

如何设置视图 widget 的透明度？

Where is the widget’s opacity?

在 iOS 里，视图都有一个 opacity 或者 alpha 属性。而在 Flutter 里，大部分时候你都需要封装 widget 到一个 Opacity widget 中来实现这一功能。

On iOS, everything has .opacity or .alpha. In Flutter, most of the time you need to wrap a widget in an Opacity widget to accomplish this.

如何构建自定义 widget？

How do I build custom widgets?

在 iOS 里，你可以直接继承 UIView 或者使用已经存在的视图，然后重写并实现对应的方法来达到想要的效果。在 Flutter 里，构建自定义 widget 需要通过组合一些小的 widget（而不是对它们进行扩展）来实现。

In iOS, you typically subclass UIView, or use a pre-existing view, to override and implement methods that achieve the desired behavior. In Flutter, build a custom widget by composing smaller widgets (instead of extending them).

例如，应该如何构建一个初始方法中就包含文本标签的 CustomButton？需要创建一个合成一个 RaisedButton 和一个文本标签的 CustomButton，而不是继承 RaisedButton：

For example, how do you build a CustomButton that takes a label in the constructor? Create a CustomButton that composes a ElevatedButton with a label, rather than by extending ElevatedButton:

class CustomButton extends StatelessWidget {
  final String label;

  CustomButton(this.label);

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(onPressed: () {}, child: Text(label));
  }
}

与其他 Flutter widget 一样的用法，下面我们使用 CustomButton：

Then use CustomButton, just as you’d use any other Flutter widget:

@override
Widget build(BuildContext context) {
  return Center(
    child: CustomButton("Hello"),
  );
}

Navigation

如何在两个页面之间切换？

How do I navigate between pages?

在 iOS 里，想要在多个 viewcontroller 中切换，可以使用 UINavigationController 管理 viewcontroller 构成的栈进行显示。

In iOS, to travel between view controllers, you can use a UINavigationController that manages the stack of view controllers to display.

Flutter 中也有类似的实现，使用 Navigator 和 Routes。一个 Route 是应用中屏幕或者页面的抽象概念，而一个 Navigator 是管多个 Route 的 widget。也可以理解把 Route 理解为 UIViewController。而 Navigator 的工作方式和 iOS 里的 UINavigationController 类似，当你想要进入或退出一个新页面的时候，它也可以进行 push() 和 pop() 操作。

To navigate between pages, you have a couple options: 想要在不同页面间跳转，你有两个选择：

Flutter has a similar implementation, using a Navigator and Routes. A Route is an abstraction for a “screen” or “page” of an app, and a Navigator is a widget that manages routes. A route roughly maps to a UIViewController. The navigator works in a similar way to the iOS UINavigationController, in that it can push() and pop() routes depending on whether you want to navigate to, or back from, a view.

构建由 route 名称组成的 Map；
Specify a Map of route names.
直接跳转到一个 route。
Directly navigate to a route.

下面的示例构建了一个 Map：

The following example builds a Map.

void main() {
  runApp(CupertinoApp(
    home: MyAppHome(), // becomes the route named '/'
    routes: <String, WidgetBuilder> {
      '/a': (BuildContext context) => MyPage(title: 'page A'),
      '/b': (BuildContext context) => MyPage(title: 'page B'),
      '/c': (BuildContext context) => MyPage(title: 'page C'),
    },
  ));
}

通过把 route 名称传递给 Navigator 来实现 push 效果。

Navigate to a route by pushing its name to the Navigator.

Navigator.of(context).pushNamed('/b');

Navigator 类对 Flutter 中的路由事件做处理，还可以用来获取入栈之后的路由的结果。这需要通过 push() 返回的 Future 中的 await 来实现。

The Navigator class handles routing in Flutter and is used to get a result back from a route that you have pushed on the stack. This is done by awaiting on the Future returned by push().

例如，要打开一个“定位”页面来让用户选择他们的位置，你需要做如下事情：

For example, to start a ‘location’ route that lets the user select their location, you might do the following:

Map coordinates = await Navigator.of(context).pushNamed('/location');

然后，在”定位“页面中，一旦用户选择了自己的定位，就 pop() 出栈并返回结果。

And then, inside your ‘location’ route, once the user has selected their location, pop() the stack with the result:

Navigator.of(context).pop({"lat":43.821757,"long":-79.226392});

如何跳转到其他应用？

How do I navigate to another app?

在 iOS 里，想要跳转到其他应用，可以使用特定的 URL scheme。对于系统级别的应用，scheme 都是取决于应用的。在 Flutter 里想要实现这个功能，需要创建原生平台的整合层，或者使用已经存在的插件，例如 url_launcher。

In iOS, to send the user to another application, you use a specific URL scheme. For the system level apps, the scheme depends on the app. To implement this functionality in Flutter, create a native platform integration, or use an existing plugin, such as url_launcher.

如何退回到 iOS 原生的 viewcontroller？

How do I pop back to the iOS native viewcontroller?

在 Dart 代码中调用 SystemNavigator.pop() 将会调用下面的 iOS 代码：

Calling SystemNavigator.pop() from your Dart code invokes the following iOS code:

UIViewController* viewController = [UIApplication sharedApplication].keyWindow.rootViewController;
  if ([viewController isKindOfClass:[UINavigationController class]]) {
    [((UINavigationController*)viewController) popViewControllerAnimated:NO];
  }

如果这不是你需要的功能，你可以创建你自己的平台通道来调用对应的 iOS 代码。

If that doesn’t do what you want, you can create your own platform channel to invoke arbitrary iOS code.

线程和异步

Threading & asynchronicity

如何编写异步代码？

How do I write asynchronous code?

Dart 是单线程执行模型，支持 Isolate（一种在其他线程运行 Dart 代码的方法）、事件循环和异步编程。除非生成了 Isolate，否则所有 Dart 代码将永远在主 UI 线程运行，并由事件循环驱动。Flutter 中的事件循环类似于 iOS 中的 main loop—，也就是主线程上的 Looper。

Dart has a single-threaded execution model, with support for Isolates (a way to run Dart code on another thread), an event loop, and asynchronous programming. Unless you spawn an Isolate, your Dart code runs in the main UI thread and is driven by an event loop. Flutter’s event loop is equivalent to the iOS main loop—that is, the Looper that is attached to the main thread.

Dart 的单线程模型并不意味着你需要以阻塞 UI 的形式来执行代码，相反，你更应该使用 Dart 语言提供的异步功能，比如使用 async/await 来实现异步操作。

Dart’s single-threaded model doesn’t mean you are required to run everything as a blocking operation that causes the UI to freeze. Instead, use the asynchronous facilities that the Dart language provides, such as async/await, to perform asynchronous work.

例如，你可以使用 async/await 来执行网络代码以避免 UI 挂起，让 Dart 来完成这个繁重的任务：

For example, you can run network code without causing the UI to hang by using async/await and letting Dart do the heavy lifting:

loadData() async {
  String dataURL = "https://jsonplaceholder.typicode.com/posts";
  http.Response response = await http.get(dataURL);
  setState(() {
    widgets = jsonDecode(response.body);
  });
}

一旦 await 等待的网络操作结束，通过调用 setState() 来更新 UI，这将会触发 widget 子树的重新构建并更新数据。

Once the awaited network call is done, update the UI by calling setState(), which triggers a rebuild of the widget sub-tree and updates the data.

下面的示例展示了如何异步加载数据，并在 ListView 中展示出来：

The following example loads data asynchronously and displays it in a ListView:

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List widgets = [];

  @override
  void initState() {
    super.initState();
    loadData();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: ListView.builder(
          itemCount: widgets.length,
          itemBuilder: (BuildContext context, int position) {
            return getRow(position);
          }));
  }

  Widget getRow(int i) {
    return Padding(
      padding: EdgeInsets.all(10.0),
      child: Text("Row ${widgets[i]["title"]}")
    );
  }

  loadData() async {
    String dataURL = "https://jsonplaceholder.typicode.com/posts";
    http.Response response = await http.get(dataURL);
    setState(() {
      widgets = jsonDecode(response.body);
    });
  }
}

更多关于在后台执行任务的信息，以及 Flutter 和 iOS 的区别，可以参考下一章节。

Refer to the next section for more information on doing work in the background, and how Flutter differs from iOS.

如何让你的任务在后台线程执行？

How do you move work to a background thread?

由于 Flutter 是单线程模型，而且执行着一个 event loop（就像 Node.js），你不需要为线程管理或是开启后台线程操心。如果你在处理 I/O 操作，例如磁盘访问或网络请求，那么你安全地使用 async/await 就可以了。但是，如果你需要大量的计算来让 CPU 保持忙碌状态，你需要使用 Isolate 来防治阻塞 event loop。

Since Flutter is single threaded and runs an event loop (like Node.js), you don’t have to worry about thread management or spawning background threads. If you’re doing I/O-bound work, such as disk access or a network call, then you can safely use async/await and you’re done. If, on the other hand, you need to do computationally intensive work that keeps the CPU busy, you want to move it to an Isolate to avoid blocking the event loop.

对于 I/O 操作，把方法声明为 async 方法，然后通过 await 来等待异步方法的执行完成：

For I/O-bound work, declare the function as an async function, and await on long-running tasks inside the function:

loadData() async {
  String dataURL = "https://jsonplaceholder.typicode.com/posts";
  http.Response response = await http.get(dataURL);
  setState(() {
    widgets = jsonDecode(response.body);
  });
}

这就是处理网络或数据库请求等 I/O 操作的经典做法。

This is how you typically do network or database calls, which are both I/O operations.

然而，有时候你需要处理大量的数据，从而导致 UI 挂起。在 Flutter 里，当处理长期运行或者运算密集的任务时，可以使用 Isolate 来发挥出多核 CPU 的优势。

Isolates 是相互隔离的执行线程，并不和主线程共享内存。这意味着你不能够访问主线程的变量，也不能使用 setState() 来更新 UI。Isolates 正如起字面意思是不能共享内存（例如静态变量表）的。

Isolates are separate execution threads that do not share any memory with the main execution memory heap. This means you can’t access variables from the main thread, or update your UI by calling setState(). Isolates are true to their name, and cannot share memory (in the form of static fields, for example).

下面的例子展示了在一个简单的 isolate 中，如何把数据推到主线程上用来更新 UI。

The following example shows, in a simple isolate, how to share data back to the main thread to update the UI.

loadData() async {
  ReceivePort receivePort = ReceivePort();
  await Isolate.spawn(dataLoader, receivePort.sendPort);

  // The 'echo' isolate sends its SendPort as the first message
  SendPort sendPort = await receivePort.first;

  List msg = await sendReceive(
    sendPort,
    "https://jsonplaceholder.typicode.com/posts",
  );

  setState(() {
    widgets = msg;
  });
}

// The entry point for the isolate
static dataLoader(SendPort sendPort) async {
  // Open the ReceivePort for incoming messages.
  ReceivePort port = ReceivePort();

  // Notify any other isolates what port this isolate listens to.
  sendPort.send(port.sendPort);

  await for (var msg in port) {
    String data = msg[0];
    SendPort replyTo = msg[1];

    String dataURL = data;
    http.Response response = await http.get(dataURL);
    // Lots of JSON to parse
    replyTo.send(jsonDecode(response.body));
  }
}

Future sendReceive(SendPort port, msg) {
  ReceivePort response = ReceivePort();
  port.send([msg, response.sendPort]);
  return response.first;
}

在这里，dataLoader 就是运行在独立线程上的 Isolate。在 Isolate 中，你可以处理 CPU 密集型任务（如解析一个庞大的 JSON 文件），或者处理复杂的数学运算，比如加密操作或者信号处理等。

下面是一个完整示例：

You can run the full example below:

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'dart:async';
import 'dart:isolate';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List widgets = [];

  @override
  void initState() {
    super.initState();
    loadData();
  }

  showLoadingDialog() {
    if (widgets.length == 0) {
      return true;
    }

    return false;
  }

  getBody() {
    if (showLoadingDialog()) {
      return getProgressDialog();
    } else {
      return getListView();
    }
  }

  getProgressDialog() {
    return Center(child: CircularProgressIndicator());
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        appBar: AppBar(
          title: Text("Sample App"),
        ),
        body: getBody());
  }

  ListView getListView() => ListView.builder(
      itemCount: widgets.length,
      itemBuilder: (BuildContext context, int position) {
        return getRow(position);
      });

  Widget getRow(int i) {
    return Padding(
      padding: EdgeInsets.all(10.0),
      child: Text("Row ${widgets[i]["title"]}"),
    );
  }

  loadData() async {
    ReceivePort receivePort = ReceivePort();
    await Isolate.spawn(dataLoader, receivePort.sendPort);

    // The 'echo' isolate sends its SendPort as the first message
    SendPort sendPort = await receivePort.first;

    List msg = await sendReceive(
      sendPort,
      "https://jsonplaceholder.typicode.com/posts",
    );

    setState(() {
      widgets = msg;
    });
  }

// the entry point for the isolate
  static dataLoader(SendPort sendPort) async {
    // Open the ReceivePort for incoming messages.
    ReceivePort port = ReceivePort();

    // Notify any other isolates what port this isolate listens to.
    sendPort.send(port.sendPort);

    await for (var msg in port) {
      String data = msg[0];
      SendPort replyTo = msg[1];

      String dataURL = data;
      http.Response response = await http.get(dataURL);
      // Lots of JSON to parse
      replyTo.send(jsonDecode(response.body));
    }
  }

  Future sendReceive(SendPort port, msg) {
    ReceivePort response = ReceivePort();
    port.send([msg, response.sendPort]);
    return response.first;
  }
}

如何发起网络请求？

How do I make network requests?

在 Flutter 里，想要构造网络请求十分简单，直接使用 http 库即可。它把你可能要实现的网络操作进行了抽象封装，让处理网络请求变得十分简单。

Making a network call in Flutter is easy when you use the popular http package. This abstracts away a lot of the networking that you might normally implement yourself, making it simple to make network calls.

要使用 http 库，需要在 pubspec.yaml 中把它添加为依赖：

To use the http package, add it to your dependencies in pubspec.yaml:

dependencies:
  ...
  http: ^0.11.3+16

构造网络请求，需要在 async 方法 http.get() 中调用 await：

To make a network call, call await on the async function http.get():

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
[...]
  loadData() async {
    String dataURL = "https://jsonplaceholder.typicode.com/posts";
    http.Response response = await http.get(dataURL);
    setState(() {
      widgets = jsonDecode(response.body);
    });
  }
}

展示耗时任务的进度

How do I show the progress of a long-running task?

在 iOS 里，在后台运行耗时任务时，会使用 UIProgressView。

In iOS, you typically use a UIProgressView while executing a long-running task in the background.

在 Flutter 里，应该使用 ProgressIndicator。它在渲染时通过一个 boolean flag 来控制是否显示进度。在耗时任务开始前，告诉 Flutter 去更新状态，并在任务结束后隐藏。

在下面的例子中，build 函数被分为三个不同的函数。当 showLoadingDialog() 是 true 时（当 widgets.length == 0），渲染 ProgressIndicator。否则，使用网络请求返回的数据渲染 ListView。

In the example below, the build function is separated into three different functions. If showLoadingDialog() is true (when widgets.length == 0), then render the ProgressIndicator. Otherwise, render the ListView with the data returned from a network call.

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List widgets = [];

  @override
  void initState() {
    super.initState();
    loadData();
  }

  showLoadingDialog() {
    return widgets.length == 0;
  }

  getBody() {
    if (showLoadingDialog()) {
      return getProgressDialog();
    } else {
      return getListView();
    }
  }

  getProgressDialog() {
    return Center(child: CircularProgressIndicator());
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        appBar: AppBar(
          title: Text("Sample App"),
        ),
        body: getBody());
  }

  ListView getListView() => ListView.builder(
      itemCount: widgets.length,
      itemBuilder: (BuildContext context, int position) {
        return getRow(position);
      });

  Widget getRow(int i) {
    return Padding(
      padding: EdgeInsets.all(10.0),
      child: Text("Row ${widgets[i]["title"]}"),
    );
  }

  loadData() async {
    String dataURL = "https://jsonplaceholder.typicode.com/posts";
    http.Response response = await http.get(dataURL);
    setState(() {
      widgets = jsonDecode(response.body);
    });
  }
}

工程结构，本地化，依赖和资源

Project structure, localization, dependencies and assets

如何在 Flutter 中引入图片资源？如何处理多分辨率？

How do I include image assets for Flutter? What about multiple resolutions?

在 iOS 里，图片和其他资源会被视为不同的资源分别处理，而在 Flutter 中只有资源这一个概念。 iOS 里被放置在 Images.xcasset 文件夹的资源在 Flutter 中都被放置到了 assets 文件夹中。和 iOS 一样，assets 中可以放置任意类型的文件，而不仅仅是图片。例如，你可以把一个 JSON 文件放置到 my-assets 文件夹中。

While iOS treats images and assets as distinct items, Flutter apps have only assets. Resources that are placed in the Images.xcasset folder on iOS, are placed in an assets folder for Flutter. As with iOS, assets are any type of file, not just images. For example, you might have a JSON file located in the my-assets folder:

my-assets/data.json

在 pubspec.yaml 中声明 assets：

Declare the asset in the pubspec.yaml file:

assets:
 - my-assets/data.json

然后在代码中通过 AssetBundle 访问资源:

And then access it from code using an AssetBundle:

import 'dart:async' show Future;
import 'package:flutter/services.dart' show rootBundle;

Future<String> loadAsset() async {
  return await rootBundle.loadString('my-assets/data.json');
}

对于图片，Flutter 和 iOS 一样遵循了一个简单的基于屏幕密度的格式。 Image assets 可能是 1.0x，2.0x，3.0x 或者其他任意的倍数。而 devicePixelRatio 则表达了物理分辨率到逻辑分辨率的对照比例。

For images, Flutter follows a simple density-based format like iOS. Image assets might be 1.0x, 2.0x, 3.0x, or any other multiplier. The so-called devicePixelRatio expresses the ratio of physical pixels in a single logical pixel.

Assets 可以放在任何属性的文件夹中—Flutter 没有任何预置的文件结构。你需要在 pubspec.yaml 中声明 assets （包括路径），然后 Flutter 将会识别它们。

Assets are located in any arbitrary folder—Flutter has no predefined folder structure. You declare the assets (with location) in the pubspec.yaml file, and Flutter picks them up.

例如，要添加一个名为 my_icon.png 的图片到你的 Flutter 工程中，你可以把它存储在 images 文件夹下。把基础的图片（一倍图）放到 images 文件夹下，然后把其他倍数的图片放置到对应的比例下的子文件夹中。

For example, to add an image called my_icon.png to your Flutter project, you might decide to store it in a folder arbitrarily called images. Place the base image (1.0x) in the images folder, and the other variants in sub-folders named after the appropriate ratio multiplier:

images/my_icon.png       // Base: 1.0x image
images/2.0x/my_icon.png  // 2.0x image
images/3.0x/my_icon.png  // 3.0x image

接着，在 pubspec.yaml 文件中声明这些图片：

Next, declare these images in the pubspec.yaml file:

assets:
 - images/my_icon.png

现在你可以使用 AssetImage 访问你的图片了：

You can now access your images using AssetImage:

return AssetImage("images/a_dot_burr.jpeg");

或者直接在 Image widget 进行使用：

or directly in an Image widget:

@override
Widget build(BuildContext context) {
  return Image.asset("images/my_image.png");
}

关于更多的细节，请参见文档在 Flutter 中添加资源和图片。

For more details, see Adding Assets and Images in Flutter.

字符串存储在哪里？如何处理本地化？

Where do I store strings? How do I handle localization?

iOS 里有 Localizable.strings 文件，而 Flutter 则不同，目前并没有关于字符串的处理系统。目前，最佳的方案就是在静态区声明你的文本，然后进行访问。例如：

Unlike iOS, which has the Localizable.strings file, Flutter doesn’t currently have a dedicated system for handling strings. At the moment, the best practice is to declare your copy text in a class as static fields and access them from there. For example:

class Strings {
  static String welcomeMessage = "Welcome To Flutter";
}

你可以这样访问字符串：

You can access your strings as such:

Text(Strings.welcomeMessage)

默认情况下，Flutter 只支持美式英语的本地化字符串。如果你需要添加其他语言支持，请引入 flutter_localizations 库。同时你可能还需要添加 intl 库来使用 i10n 机制，比如日期 / 时间的格式化等。

By default, Flutter only supports US English for its strings. If you need to add support for other languages, include the flutter_localizations package. You might also need to add Dart’s intl package to use i10n machinery, such as date/time formatting.

dependencies:
  # ...
  flutter_localizations:
    sdk: flutter
  intl: "^0.15.6"

To use the flutter_localizations package, specify the localizationsDelegates and supportedLocales on the app widget:

import 'package:flutter_localizations/flutter_localizations.dart';

MaterialApp(
 localizationsDelegates: const [
   // Add app-specific localization delegate[s] here
   GlobalMaterialLocalizations.delegate,
   GlobalWidgetsLocalizations.delegate,
 ],
 supportedLocales: const [
    Locale('en', 'US'), // English
    Locale('he', 'IL'), // Hebrew
    // ... other locales the app supports
  ],
  // ...
)

supportedLocales 指定了应用支持的语言，而这些 delegates 则包含了实际的本地化内容。上面的示例使用了一个 MaterialApp，所以它既使用了处理基础 widget 本地化的 GlobalWidgetsLocalizations，也使用了处理 Material widget 本地化的 MaterialWidgetsLocalizations。如果你在应用中使用的是 WidgetApp，就不需要后者了。注意，这两个 delegates 虽然都包含了“默认”值，但是如果你想要实现本地化，就必须在本地提供一个或多个 delegates 的实现副本。

The delegates contain the actual localized values, while the supportedLocales defines which locales the app supports. The above example uses a MaterialApp, so it has both a GlobalWidgetsLocalizations for the base widgets localized values, and a MaterialWidgetsLocalizations for the Material widgets localizations. If you use WidgetsApp for your app, you don’t need the latter. Note that these two delegates contain “default” values, but you’ll need to provide one or more delegates for your own app’s localizable copy, if you want those to be localized too.

当初始化的时候，WidgetsApp（或 MaterialApp）会根据你提供的 delegates 创建一个 Localizations widget。 Localizations widget 可以随时从当前上下文中中获取设备所用的语言，也可以使用 Window.locale。

When initialized, the WidgetsApp (or MaterialApp) creates a Localizations widget for you, with the delegates you specify. The current locale for the device is always accessible from the Localizations widget from the current context (in the form of a Locale object), or using the Window.locale.

要使用本地化资源，使用 Localizations.of() 方法可以访问提供代理的特定本地化类。使用 intl_translation 库解压翻译的副本到 arb 文件，然后在应用中通过 intl 来引用它们。

To access localized resources, use the Localizations.of() method to access a specific localizations class that is provided by a given delegate. Use the intl_translation package to extract translatable copy to arb files for translating, and importing them back into the app for using them with intl.

关于 Flutter 中国际化和本地化的细节内容，请参看 Flutter 应用里的国际化，里面包含有使用和不使用 intl 库的示例代码。

For further details on internationalization and localization in Flutter, see the internationalization guide, which has sample code with and without the intl package.

注意在 Flutter 1.0 beta 2 之前，在 Flutter 里定义的资源是不能被原生代码访问的，反之亦然，而原生的资源也是不能在 Flutter 中使用，因为它们都被放在了独立的文件夹中。

CocoaPods 相当于 Flutter 中的什么？如何添加依赖？

What is the equivalent of CocoaPods? How do I add dependencies?

在 iOS 里，可以通过 Podfile 添加依赖。而 Flutter 使用 Dart 构建系统和 Pub 包管理器来处理依赖。这些工具将原生应用的打包任务分发给相应 Android 或 iOS 构建系统。

In iOS, you add dependencies by adding to your Podfile. Flutter uses Dart’s build system and the Pub package manager to handle dependencies. The tools delegate the building of the native Android and iOS wrapper apps to the respective build systems.

如果你的 Flutter 项目 iOS 文件夹中存在 Podfile，那么请仅在里面添加原生平台的依赖。总而言之，在 Flutter 中使用 pubspec.yaml 来声明外部依赖。你可以通过 pub.dev 来查找一些优秀的 Flutter 第三方包。

While there is a Podfile in the iOS folder in your Flutter project, only use this if you are adding native dependencies needed for per-platform integration. In general, use pubspec.yaml to declare external dependencies in Flutter. A good place to find great packages for Flutter is on pub.dev.

ViewControllers

ViewControllers 相当于 Flutter 中的什么？

What is the equivalent to ViewController in Flutter?

在 iOS 里，一个 ViewController 是用户界面的一部分，通常是作为屏幕或者其中的一部分来使用。这些组合在一起构成了复杂的用户界面，并以此对应用的 UI 做不断的扩充。在 Flutter 中，这一任务又落到了 Widget 这里。就像在导航那一章提到的， Flutter 中的屏幕也是使用 Widgets 表示的，因为“万物皆 widget！”。使用 Naivgator 在不同的 Route 之间切换，而不同的路由则代表了不同的屏幕或页面，或是不同的状态，也可能是渲染相同的数据。

In iOS, a ViewController represents a portion of user interface, most commonly used for a screen or section. These are composed together to build complex user interfaces, and help scale your application’s UI. In Flutter, this job falls to Widgets. As mentioned in the Navigation section, screens in Flutter are represented by Widgets since “everything is a widget!” Use a Navigator to move between different Routes that represent different screens or pages, or maybe different states or renderings of the same data.

如何监听 iOS 中的生命周期？

How do I listen to iOS lifecycle events?

在 iOS 里，可以重写 ViewController 的方法来捕获自身的生命周期，或者在 AppDelegate 中注册生命周期的回调。Flutter 中则没有这两个概念，但是你可以通过在 WidgetsBinding 的 observer 中挂钩子，也可以通过监听 didChangeAppLifecycleState() 事件，来实现相应的功能。

In iOS, you can override methods to the ViewController to capture lifecycle methods for the view itself, or register lifecycle callbacks in the AppDelegate. In Flutter you have neither concept, but you can instead listen to lifecycle events by hooking into the WidgetsBinding observer and listening to the didChangeAppLifecycleState() change event.

可监听的生命周期事件有：

The observable lifecycle events are:

inactive
应用当前处于不活跃状态，不接收用户输入事件。这个事件只在 iOS 上有效，Android 中没有类似的状态。

inactive
The application is in an inactive state and is not receiving user input. This event only works on iOS, as there is no equivalent event on Android.

paused
应用当前处于用户不可见状态，不接收用户输入事件，但仍在后台运行。

paused
The application is not currently visible to the user, is not responding to user input, but is running in the background.

resumed
应用可见，也响应用户输入。

resumed
The application is visible and responding to user input.

suspending
应用被挂起，在 iOS 平台没有这一事件。

suspending
The application is suspended momentarily. The iOS platform has no equivalent event.

关于这些状态含义的更多细节，请参看 AppLifecycleStatus 文档。

For more details on the meaning of these states, see AppLifecycleState documentation.

布局

Layouts

`UITableView` 和 `UICollectionView` 相当于 Flutter 中的什么？

What is the equivalent of UITableView or UICollectionView in Flutter?

在 iOS 里，你可能使用 UITableView 或者 UICollectionView 来展示一个列表。而在 Flutter 里，你可以使用 ListView 来达到类似的实现。在 iOS 中，你通过 delegate 方法来确定显示的行数，相应位置的 cell，以及 cell 的尺寸。

In iOS, you might show a list in either a UITableView or a UICollectionView. In Flutter, you have a similar implementation using a ListView. In iOS, these views have delegate methods for deciding the number of rows, the cell for each index path, and the size of the cells.

由于 Flutter 中 widget 的不可变特性，你需要向 ListView 传递一个 widget 列表，Flutter 会确保滚动快速而流畅。

Due to Flutter’s immutable widget pattern, you pass a list of widgets to your ListView, and Flutter takes care of making sure that scrolling is fast and smooth.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: ListView(children: _getListData()),
    );
  }

  _getListData() {
    List<Widget> widgets = [];
    for (int i = 0; i < 100; i++) {
      widgets.add(Padding(padding: EdgeInsets.all(10.0), child: Text("Row $i")));
    }
    return widgets;
  }
}

如何确定列表中被点击的元素？

How do I know which list item is clicked?

在 iOS 里，可以通过 tableView:didSelectRowAtIndexPath: 代理方法来实现。而在 Flutter 里，需要通过 widget 传递进来的 touch 响应处理来实现。

In iOS, you implement the delegate method, tableView:didSelectRowAtIndexPath:. In Flutter, use the touch handling provided by the passed-in widgets.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: ListView(children: _getListData()),
    );
  }

  _getListData() {
    List<Widget> widgets = [];
    for (int i = 0; i < 100; i++) {
      widgets.add(GestureDetector(
        child: Padding(
          padding: EdgeInsets.all(10.0),
          child: Text("Row $i"),
        ),
        onTap: () {
          print('row tapped');
        },
      ));
    }
    return widgets;
  }
}

如何动态更新 `ListView`？

How do I dynamically update a ListView?

在 iOS 里，可以更新列表的数据，然后通过调用 reloadData 方法来通知 tableView 或者 collectionView。

In iOS, you update the data for the list view, and notify the table or collection view using the reloadData method.

在 Flutter 里，如果你在 setState() 中更新了 widget 列表，你会发现展示的数据并不会立刻更新。这是因为当 setState() 被调用时，Flutter 的渲染引擎回去检索 widget 树是否有改变。当它获取到 ListView，会进行 == 判断，然后发现两个 ListView 是相等的。没发现有改变，所以也就不会进行更新。

In Flutter, if you update the list of widgets inside a setState(), you quickly see that your data doesn’t change visually. This is because when setState() is called, the Flutter rendering engine looks at the widget tree to see if anything has changed. When it gets to your ListView, it performs an == check, and determines that the two ListViews are the same. Nothing has changed, so no update is required.

一个更新 ListView 的简单方法就是，在 setState() 创建一个新的 List，然后拷贝旧列表中的所有数据到新列表。这样虽然简单，但是像下面示例一样数据量很大时，并不推荐这样做。

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List<Widget> widgets = [];

  @override
  void initState() {
    super.initState();
    for (int i = 0; i < 100; i++) {
      widgets.add(getRow(i));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: ListView(children: widgets),
    );
  }

  Widget getRow(int i) {
    return GestureDetector(
      child: Padding(
        padding: EdgeInsets.all(10.0),
        child: Text("Row $i"),
      ),
      onTap: () {
        setState(() {
          widgets = List.from(widgets);
          widgets.add(getRow(widgets.length));
          print('row $i');
        });
      },
    );
  }
}

一个推荐的、高效且有效的方法就是使用 ListView.Builder 来构建列表。当你的数据量很大，且需要构建动态列表时，这个方法会非常好用。

The recommended, efficient, and effective way to build a list uses a ListView.Builder. This method is great when you have a dynamic list or a list with very large amounts of data.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List<Widget> widgets = [];

  @override
  void initState() {
    super.initState();
    for (int i = 0; i < 100; i++) {
      widgets.add(getRow(i));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: ListView.builder(
        itemCount: widgets.length,
        itemBuilder: (BuildContext context, int position) {
          return getRow(position);
        },
      ),
    );
  }

  Widget getRow(int i) {
    return GestureDetector(
      child: Padding(
        padding: EdgeInsets.all(10.0),
        child: Text("Row $i"),
      ),
      onTap: () {
        setState(() {
          widgets.add(getRow(widgets.length));
          print('row $i');
        });
      },
    );
  }
}

和创建 ListView 不同，创建 ListView.Builder 需要两个关键参数：初始化列表长度和 ItemBuilder 函数。

Instead of creating a ListView, create a ListView.builder that takes two key parameters: the initial length of the list, and an ItemBuilder function.

ItemBuilder 函数和 iOS 里 tableView 和 collectionView 的 cellForItemAt 方法类似，它接收位置参数，然后返回想要在该位置渲染的 cell。

The ItemBuilder function is similar to the cellForItemAt delegate method in an iOS table or collection view, as it takes a position, and returns the cell you want rendered at that position.

最后，也是最重要的，注意 onTap() 方法并没有重新创建列表，而是使用 .add 方法进行添加。

Finally, but most importantly, notice that the onTap() function doesn’t recreate the list anymore, but instead .adds to it.

`ScrollView` 相当于 Flutter 中的什么？

What is the equivalent of a ScrollView in Flutter?

在 iOS 里，把视图放在 ScrollView 里来允许用户在需要时滚动内容。

In iOS, you wrap your views in a ScrollView that allows a user to scroll your content if needed.

在 Flutter 中，最简单的办法就是使用 ListView widget。它和 iOS 中的 ScrollView 以及 TableView 表现一致，也可以给它的子 widget 做垂直排版。

In Flutter the easiest way to do this is using the ListView widget. This acts as both a ScrollView and an iOS TableView, as you can layout widgets in a vertical format.

@override
Widget build(BuildContext context) {
  return ListView(
    children: <Widget>[
      Text('Row One'),
      Text('Row Two'),
      Text('Row Three'),
      Text('Row Four'),
    ],
  );
}

关于 Flutter 中布局的更多细节，请参看布局教程。

For more detailed docs on how to lay out widgets in Flutter, see the layout tutorial.

手势检测与 touch 事件处理

Gesture detection and touch event handling

How do I add a click listener to a widget in Flutter?

在 iOS 里，通过把 GestureRecognizer 绑定给 UIView 来处理点击事件。在 Flutter 中，有两种方法来添加事件监听者：

In iOS, you attach a GestureRecognizer to a view to handle click events. In Flutter, there are two ways of adding touch listeners:

如果 widget 本身支持事件检测，则直接传递处理函数给它。例如，ElevatedButton 拥有一个 onPressed 参数：
If the widget supports event detection, pass a function to it, and handle the event in the function. For example, the ElevatedButton widget has an onPressed parameter:
```
@override
Widget build(BuildContext context) {
  return ElevatedButton(
    onPressed: () {
      print("click");
    },
    child: Text("Button"),
  );
}
```

如果 widget 本身不支持事件检测，那么把它封装到一个 GestureDetector 中，并给它的 onTap 参数传递一个函数：

If the Widget doesn’t support event detection, wrap the widget in a GestureDetector and pass a function to the onTap parameter.

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: GestureDetector(
          child: FlutterLogo(
            size: 200.0,
          ),
          onTap: () {
            print("tap");
          },
        ),
      ),
    );
  }
}

如何处理 widget 的其他手势？

How do I handle other gestures on widgets?

你可以使用 GestureDetector 来监听更多的手势，例如：

Using GestureDetector you can listen to a wide range of gestures such as:

单击事件
Tapping

onTapDown
用户在特定区域发生点触屏幕的一个即时操作。
onTapDown
A pointer that might cause a tap has contacted the screen at a particular location.

onTapUp
用户在特定区域发生触摸抬起的一个即时操作。
onTapUp
A pointer that triggers a tap has stopped contacting the screen at a particular location.

onTap
从点触屏幕之后到触摸抬起之间的单击操作。
onTap
A tap has occurred.

onTapCancel
用户在之前触发了 onTapDown 时间，但未触发 tap 事件。
onTapCancel
The pointer that previously triggered the onTapDown won’t cause a tap.
双击事件
Double tapping

onDoubleTap
用户在同一位置发生快速点击屏幕两次的操作。
onDoubleTap
The user tapped the screen at the same location twice in quick succession.
长按事件
Long pressing

onLongPress
用户在同一位置长时间触摸屏幕的操作。
onLongPress
A pointer has remained in contact with the screen at the same location for a long period of time.
垂直拖动事件
Vertical dragging

onVerticalDragStart
用户手指接触屏幕，并且将要进行垂直移动事件。
onVerticalDragStart
A pointer has contacted the screen and might begin to move vertically.

onVerticalDragUpdate
用户手指接触屏幕，已经开始垂直移动，且会持续进行移动。
onVerticalDragUpdate
A pointer in contact with the screen has moved further in the vertical direction.

onVerticalDragEnd
用户之前手指接触了屏幕并发生了垂直移动操作，并且停止接触前还在以一定的速率移动。
onVerticalDragEnd
A pointer that was previously in contact with the screen and moving vertically is no longer in contact with the screen and was moving at a specific velocity when it stopped contacting the screen.
水平拖动事件
Horizontal dragging

onHorizontalDragStart
用户手指接触屏幕，并且将要进行水平移动事件。
onHorizontalDragStart
A pointer has contacted the screen and might begin to move horizontally.

onHorizontalDragUpdate
用户手指接触屏幕，已经开始水平移动，且会持续进行移动。
onHorizontalDragUpdate
A pointer in contact with the screen has moved further in the horizontal direction.

onHorizontalDragEnd
用户之前手指接触了屏幕并发生了水平移动操作，并且停止接触前还在以一定的速率移动。
onHorizontalDragEnd
A pointer that was previously in contact with the screen and moving horizontally is no longer in contact with the screen.

下面的示例展示了 GestureDetector 是如何实现双击时旋转 Flutter 的 logo 的：

AnimationController controller;
CurvedAnimation curve;

@override
void initState() {
  super.initState();
  controller = AnimationController(duration: const Duration(milliseconds: 2000), vsync: this);
  curve = CurvedAnimation(parent: controller, curve: Curves.easeIn);
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: GestureDetector(
          child: RotationTransition(
            turns: curve,
            child: FlutterLogo(
              size: 200.0,
            )),
          onDoubleTap: () {
            if (controller.isCompleted) {
              controller.reverse();
            } else {
              controller.forward();
            }
          },
        ),
      ),
    );
  }
}

主题和文字

Theming and text

如何设置应用主题？

How do I theme an app?

Flutter 实现了一套漂亮的 Material Design 组件，而且开箱可用，它提供了许多常用的样式和主题。

Out of the box, Flutter comes with a beautiful implementation of Material Design, which takes care of a lot of styling and theming needs that you would typically do.

为了充分发挥应用中 Material Components 的优势，声明一个顶级的 widget，MaterialApp，来作为你的应用入口。 MaterialApp 是一个封装了大量常用 Material Design 组件的 widget。它基于 WidgetsApp 添加了 Material 的相关功能。

To take full advantage of Material Components in your app, declare a top-level widget, MaterialApp, as the entry point to your application. MaterialApp is a convenience widget that wraps a number of widgets that are commonly required for applications implementing Material Design. It builds upon a WidgetsApp by adding Material specific functionality.

但是 Flutter 有足够的灵活性和表现力来实现任何设计语言。在 iOS 上，可以使用 Cupertino library 来制作遵循人机接口指南的界面。关于这些 widget 的全部集合，可以参看 Cupertino widgets gallery。

But Flutter is flexible and expressive enough to implement any design language. On iOS, you can use the Cupertino library to produce an interface that adheres to the Human Interface Guidelines. For the full set of these widgets, see the Cupertino widgets gallery.

也可以使用 WidgetApp 来做为应用入口，它提供了一部分类似的功能接口，但是不如 MaterialApp 强大。

You can also use a WidgetsApp as your app widget, which provides some of the same functionality, but is not as rich as MaterialApp.

定义所有子组件颜色和样式，可以直接传递 ThemeData 对象给 MaterialApp widget。例如在下面的代码中，primary swatch 被设置为蓝色，而文本选中后的颜色被设置为红色。

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
        textSelectionColor: Colors.red
      ),
      home: SampleAppPage(),
    );
  }
}

如何给 `Text` widget 设置自定义字体？

How do I set custom fonts on my Text widgets?

在 iOS 里，可以在项目中引入任何的 ttf 字体文件，并在 info.plist 文件中声明并进行引用。在 Flutter 里，把字体放到一个文件夹中，然后在 pubspec.yaml 文件中引用它，就和引用图片一样。

In iOS, you import any ttf font files into your project and create a reference in the info.plist file. In Flutter, place the font file in a folder and reference it in the pubspec.yaml file, similar to how you import images.

fonts:
   - family: MyCustomFont
     fonts:
       - asset: fonts/MyCustomFont.ttf
       - style: italic

然后在 Text widget 中指定字体：

Then assign the font to your Text widget:

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(
      title: Text("Sample App"),
    ),
    body: Center(
      child: Text(
        'This is a custom font text',
        style: TextStyle(fontFamily: 'MyCustomFont'),
      ),
    ),
  );
}

如何设置 `Text` widget 的样式？

How do I style my Text widgets?

除了字体以外，你也可以自定义 Text widget 的其他样式。Text widget 接收一个 TextStyle 对象的参数，可以指定很多参数，例如：

Along with fonts, you can customize other styling elements on a Text widget. The style parameter of a Text widget takes a TextStyle object, where you can customize many parameters, such as:

color
decoration
decorationColor
decorationStyle
fontFamily
fontSize
fontStyle
fontWeight
hashCode
height
inherit
letterSpacing
textBaseline
wordSpacing

表单输入

Form input

Flutter 中如何使用表单？如何获取到用户的输入？

How do forms work in Flutter? How do I retrieve user input?

我们知道 Flutter 使用的是不可变而且状态分离的 widget，你可能会好奇这种情况下如何处理用户的输入。在 iOS 上，一般会在提交数据时查询当前组件的数值或动作。那么在 Flutter 中会怎么样呢？

Given how Flutter uses immutable widgets with a separate state, you might be wondering how user input fits into the picture. On iOS, you usually query the widgets for their current values when it’s time to submit the user input, or action on it. How does that work in Flutter?

和 Flutter 的其他部分一样，表单处理要通过特定的 widget 来实现。如果你有一个 TextField 或者 TextFormField，你可以通过 TextEditingController 来获取用户的输入：

In practice forms are handled, like everything in Flutter, by specialized widgets. If you have a TextField or a TextFormField, you can supply a TextEditingController to retrieve user input:

class _MyFormState extends State<MyForm> {
  // Create a text controller and use it to retrieve the current value.
  // of the TextField!
  final myController = TextEditingController();

  @override
  void dispose() {
    // Clean up the controller when disposing of the Widget.
    myController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Retrieve Text Input'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: TextField(
          controller: myController,
        ),
      ),
      floatingActionButton: FloatingActionButton(
        // When the user presses the button, show an alert dialog with the
        // text the user has typed into our text field.
        onPressed: () {
          return showDialog(
            context: context,
            builder: (context) {
              return AlertDialog(
                // Retrieve the text the user has typed in using our
                // TextEditingController
                content: Text(myController.text),
              );
            },
          );
        },
        tooltip: 'Show me the value!',
        child: Icon(Icons.text_fields),
      ),
    );
  }
}

你在 Flutter Cookbook 的获取文本框的输入值教程中可以找到更多的相关内容以及详细的代码列表。

You can find more information and the full code listing in Retrieve the value of a text field, from the Flutter cookbook.

TextField 中的 placeholder 相当于什么？

What is the equivalent of a placeholder in a text field?

在 Flutter 里，通过向 Text widget 传递一个 InputDecoration 对象，你可以轻易的显示文本框的提示信息，或是 placeholder。

In Flutter you can easily show a “hint” or a placeholder text for your field by adding an InputDecoration object to the decoration constructor parameter for the Text widget:

body: Center(
  child: TextField(
    decoration: InputDecoration(hintText: "This is a hint"),
  ),
)

如何展示验证错误信息？

How do I show validation errors?

就和显示提示信息一样，你可以通过向 Text widget 传递一个 InputDecoration 来实现。

Just as you would with a “hint”, pass an InputDecoration object to the decoration constructor for the Text widget.

然而，你并不想在一开始就显示错误信息。相反，在用户输入非法数据后，应该更新状态，并传递一个新的 InputDecoration 对象。

However, you don’t want to start off by showing an error. Instead, when the user has entered invalid data, update the state, and pass a new InputDecoration object.

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  String _errorText;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: Center(
        child: TextField(
          onSubmitted: (String text) {
            setState(() {
              if (!isEmail(text)) {
                _errorText = 'Error: This is not an email';
              } else {
                _errorText = null;
              }
            });
          },
          decoration: InputDecoration(hintText: "This is a hint", errorText: _getErrorText()),
        ),
      ),
    );
  }

  _getErrorText() {
    return _errorText;
  }

  bool isEmail(String emailString) {
    String emailRegexp =
        r'^(([^<>()[\]\\.,;:\s@\"]+(\.[^<>()[\]\\.,;:\s@\"]+)*)|(\".+\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$';

    RegExp regExp = RegExp(emailRegexp);

    return regExp.hasMatch(emailString);
  }
}

和硬件、第三方服务以及系统平台交互

Interacting with hardware, third party services and the platform

如何与系统平台以及平台原生代码进行交互？

How do I interact with the platform, and with platform native code?

Flutter 并不直接在平台上运行代码；而是以 Dart 代码的方式原生运行于设备之上，这算是绕过了平台的 SDK 的限制。这意味着，例如，你用 Dart 发起了一个网络请求，它会直接在 Dart 的上下文中运行。你不需要调用写 iOS 或者 Android 原生应用时常用的 API 接口。你的 Flutter 应用仍旧被原生平台的 ViewController 当做一个 view 来管理，但是你不能够直接访问 ViewController 自身或是对应的原生框架。

Flutter doesn’t run code directly on the underlying platform; rather, the Dart code that makes up a Flutter app is run natively on the device, “sidestepping” the SDK provided by the platform. That means, for example, when you perform a network request in Dart, it runs directly in the Dart context. You don’t use the Android or iOS APIs you normally take advantage of when writing native apps. Your Flutter app is still hosted in a native app’s ViewController as a view, but you don’t have direct access to the ViewController itself, or the native framework.

这并不意味着 Flutter 应用不能够和原生 API，或是原生代码进行交互。 Flutter 提供了用来和宿主 ViewController 通信和交换数据的平台通道。平台通道本质上是一个桥接了 Dart 代码与宿主 ViewController 和 iOS 框架的异步通信模型。你可以通过平台通道来执行原生代码的方法，或者获取设备的传感器信息等数据。

This doesn’t mean Flutter apps cannot interact with those native APIs, or with any native code you have. Flutter provides the platform channel, which communicates and exchanges data with the ViewController that hosts your Flutter view. Platform channels are essentially an asynchronous messaging mechanism that bridge the Dart code with the host ViewController and the iOS framework it runs on. You can use platform channels to execute a method on the native side, or to retrieve some data from the device’s sensors, for example.

除了直接使用 platform channels 之外，也可以使用一系列包含了原生代码和 Dart代码，实现了特定功能的现有插件。例如，你在 Flutter 中可以直接使用插件来访问相册或是设备摄像头，而不需要自己重新集成。 pub.dev 是一个 Dart 和 Flutter 的开源包仓库，你可以在这里找到需要的插件。有些包可能支持集成 iOS 或 Android，或两者皆有。

In addition to directly using platform channels, you can use a variety of pre-made plugins that encapsulate the native and Dart code for a specific goal. For example, you can use a plugin to access the camera roll and the device camera directly from Flutter, without having to write your own integration. Plugins are found on pub.dev, Dart and Flutter’s open source package repository. Some packages might support native integrations on iOS, Android, web, or all of the above.

如果你在 Pub 找不到自己需要的包，你可以自己写一个，相关信息可以查阅 Flutter Packages 的开发和提交，并且你可以将其发布到 Pub 上。

If you can’t find a plugin on pub.dev that fits your needs, you can write your own and publish it on pub.dev.

如何访问 GPS 传感器？

How do I access the GPS sensor?

使用 geolocator 插件，这一插件由社区提供。

Use the geolocator community plugin.

如何访问相机？

How do I access the camera?

image_picker 是常用的访问相机的插件。

The image_picker plugin is popular for accessing the camera.

如何使用 Facebook 登录？

How do I log in with Facebook?

To log in with Facebook, use the flutter_facebook_login community plugin.

如何集成 Firebase 的功能？

How do I use Firebase features?

大多数的 Firebase 特性都在官方维护的插件中实现了。这些插件由 Flutter 官方团队维护：

Most Firebase functions are covered by first party plugins. These plugins are first-party integrations, maintained by the Flutter team:

搭配 firebase_admob 插件来使用 Firebase AdMob
firebase_admob for Firebase AdMob
搭配 firebase_analytics 插件来使用 Firebase Analytics
firebase_analytics for Firebase Analytics
搭配 firebase_auth 插件来使用 Firebase Auth
firebase_auth for Firebase Auth
搭配 firebase_core 插件来使用 Firebase 核心库
firebase_core for Firebase’s Core package
搭配 firebase_database 插件来使用 Firebase RTDB
firebase_database for Firebase RTDB
搭配 firebase_storage 插件来使用 Firebase Cloud Storage
firebase_storage for Firebase Cloud Storage
搭配 firebase_messaging 插件来使用 Firebase Messaging (FCM)
firebase_messaging for Firebase Messaging (FCM)
搭配 cloud_firestore 插件来使用 Firebase Cloud Firestore
cloud_firestore for Firebase Cloud Firestore

在 pub.dev 上你也可以找到一些第三方的 Firebase 插件，主要实现了官方插件没有直接实现的功能。

You can also find some third-party Firebase plugins on pub.dev that cover areas not directly covered by the first-party plugins.

如何构建自己的插件？

How do I build my own custom native integrations?

如果有一些 Flutter 和遗漏的平台特性，可以根据 developing packages and plugins 构建自己的插件。

If there is platform-specific functionality that Flutter or its community Plugins are missing, you can build your own following the developing packages and plugins page.

Flutter 的插件结构，简单来说，更像是 Android 中的 Event bus：你发送一个消息，并让接受者处理并反馈结果给你。这种情况下，接受者就是在 iOS 或 Android 的原生代码。

数据库和本地存储

Databases and local storage

Flutter 中如何访问 UserDefaults？

How do I access UserDefault in Flutter?

在 iOS 里，可以使用属性列表存储一个键值对的集合，也就是我们所说的 UserDefaults。

In iOS, you can store a collection of key-value pairs using a property list, known as the UserDefaults.

在 Flutter 里，可以使用 Shared Preferences 插件来实现相同的功能。这个插件封装了 UserDefaults 以及 Android 里类似的 SharedPreferences。

In Flutter, access equivalent functionality using the Shared Preferences plugin. This plugin wraps the functionality of both UserDefaults and the Android equivalent, SharedPreferences.

CoreData 相当于 Flutter 中的什么？

What is the equivalent to CoreData in Flutter?

在 iOS 里，你可以使用 CoreData 来存储结构化的数据。这是一个基于 SQL 数据库的上层封装，可以使关联模型的查询变得更加简单。

In iOS, you can use CoreData to store structured data. This is simply a layer on top of an SQL database, making it easier to make queries that relate to your models.

在 Flutter 里，可以使用 SQFlite 插件来实现这个功能。

In Flutter, access this functionality using the SQFlite plugin.

Debugging

应该使用什么工具调试我的 Flutter 应用？

What tools can I use to debug my app in Flutter?

请使用开发者工具 debug 你的 Flutter 和 Dart 应用。

Use the DevTools suite for debugging Flutter or Dart apps.

通知

Notifications

如何设置推送通知？

How do I set up push notifications?

在 iOS 里，你需要向开发者中心注册来允许推送通知。

In iOS, you need to register your app on the developer portal to allow push notifications.

在 Flutter 里，使用 firebase_messaging 插件来实现这个功能。

In Flutter, access this functionality using the firebase_messaging plugin.

关于 Firebase Cloud Messaging API 的更多信息，可以查看 firebase_messaging 插件文档。

For more information on using the Firebase Cloud Messaging API, see the firebase_messaging plugin documentation.

给 React Native 开发者的 Flutter 指南

针对 JavaScript 开发者的 Dart 介绍
Introduction to Dart for JavaScript Developers
基本知识
The basics
项目结构和资源
Project structure and resources
Flutter widgets
视图
Views
布局
Layouts
- 如何使用 widget 来定义布局属性？
  How do I use widgets to define layout properties?
- 如何为 widget 分层？
  How do I layer widgets?
风格化
Styling
状态管理
State management
Props
本地存储
Local storage
- 如何存储在应用程序中全局有效的键值对？
  How do I store persistent key-value pairs that are global to the app?
路径
Routing
- 如何在页面之间进行切换？
  How do I navigate between screens?
- 如何使用 tab 导航和 drawer 导航？
  How do I use tab navigation and drawer navigation?
  - Tab 导航
    Tab navigation
  - Drawer 导航
    Drawer navigation
手势检测和触摸事件处理
Gesture detection and touch event handling
- 如何为 widget 添加点击或者按压的监听器？
  How do I add a click or press listeners to a widget?
发起 HTTP 网络请求
Making HTTP network requests
- 如何通过 API 调用来获得数据呢？
  How do I fetch data from API calls?
输入表单
Form input
- 如何使用文本输入 widget ？
  How do I use text field widgets?
- 如何使用 Form widget 呢？
  How do I use Form widgets?
平台相关代码
Platform-specific code
调试
Debugging
动画
Animation
- 如何添加一个简单的淡入动画效果？
  How do I add a simple fade-in animation?
- 如何为卡片添加滑动动画呢？
  How do I add swipe animation to cards?
React Native 和 Flutter widget 对等的组件
React Native and Flutter widget equivalent components

本文面向希望基于现有的 React Native 的知识结构使用 Flutter 开发移动端应用的开发者。如果你已经对 RN 的框架有所了解，那么你可以通过这个文档入门 Flutter 开发。

This document is for React Native (RN) developers looking to apply their existing RN knowledge to build mobile apps with Flutter. If you understand the fundamentals of the RN framework then you can use this document as a way to get started learning Flutter development.

本文可以当做查询手册使用，里面涉及到的问题基本上可以满足需求。

This document can be used as a cookbook by jumping around and finding questions that are most relevant to your needs.

针对 JavaScript 开发者的 Dart 介绍

Introduction to Dart for JavaScript Developers

和 React Native 一样，Flutter 使用 reactive 风格的视图。然而，RN 需要被转译为本地对应的 widget，而 Flutter 是直接编译成本地原生代码。 Flutter 可以控制屏幕上的每一个像素，如此可以避免由于使用 JavaScript Bridge 导致的性能问题。

Like React Native, Flutter uses reactive-style views. However, while RN transpiles to native widgets, Flutter compiles all the way to native code. Flutter controls each pixel on the screen, which avoids performance problems caused by the need for a JavaScript bridge.

Dart 学习起来非常简单而且有如下特性：

Dart is an easy language to learn and offers the following features:

它针对 web 服务和移动应用开发提供了一种开源的，可扩展的编程语言。
Provides an open-source, scalable programming language for building web, server, and mobile apps.
它提供了一种面向对象的单继承语言，使用 C 语言风格的语法并且可通过 AOT 编译为本地代码。
Provides an object-oriented, single inheritance language that uses a C-style syntax that is AOT-compiled into native.
可转译为 JavaScript 代码。
Transcompiles optionally into JavaScript.
支持接口和抽象类。
Supports interfaces and abstract classes.

下面的几个例子解释了 JavaScript 和 Dart 的区别。

A few examples of the differences between JavaScript and Dart are described below.

入口函数

Entry point

JavaScript 并没有预定义的入口函数。

JavaScript doesn’t have a pre-defined entry function—you define the entry point.

// JavaScript
function startHere() {
  // Can be used as entry point
}

在 Dart 里，每个应用程序必须有一个最顶级的 main() 函数，该函数作为应用程序的入口函数。

In Dart, every app must have a top-level main() function that serves as the entry point to the app.

// Dart
main() {
}

可以在这里查看效果 DartPad。

Try it out in DartPad.

在控制台打印输出

Printing to the console

在 Dart 中如果需要在控制台进行输出，调用 print()。

To print to the console in Dart, use print().

// JavaScript
console.log('Hello world!');

// Dart
print('Hello world!');

可以在这里查看效果 DartPad。

Try it out in DartPad.

变量

Variables

Dart 是类型安全的，它结合静态类型检查和运行时检查来保证变量的值总是和变量的静态类型相匹配。虽然类型是语法要求，有些类型标注也并不是必须要填的，因为 Dart 使用类型推断。

Dart is type safe—it uses a combination of static type checking and runtime checks to ensure that a variable’s value always matches the variable’s static type. Although types are mandatory, some type annotations are optional because Dart performs type inference.

创建变量并赋值

Creating and assigning variables

在 JavaScript 中，变量是无法指定类型的。

In JavaScript, variables cannot be typed.

在 Dart 中，变量要么被显式定义类型，要么系统会自动判断变量的类型。

In Dart, variables must either be explicitly typed or the type system must infer the proper type automatically.

// JavaScript
var name = 'JavaScript';

// Dart
String name = 'dart'; // Explicitly typed as a string.
var otherName = 'Dart'; // Inferred string.
// Both are acceptable in Dart.

可以在这里查看效果 DartPad。

Try it out in DartPad.

如果想了解更多相关信息，请参考 Dart 的类型系统。

For more information, see Dart’s Type System.

默认值

Default value

在 JavaScript 中，未初始化的变量是 undefined。

In JavaScript, uninitialized variables are undefined.

在 Dart 中，未初始化的变量会有一个初始值 null。因为数字在 Dart 是对象，甚至未初始化的数字类型的变量也会是 null。

In Dart, uninitialized variables have an initial value of null. Because numbers are objects in Dart, even uninitialized variables with numeric types have the value null.

// JavaScript
var name; // == undefined

// Dart
var name; // == null
int x; // == null

可以在这里查看效果 DartPad。

Try it out in DartPad.

如果想了解更多详细内容，请查看这个文档 variables。

For more information, see the documentation on variables.

检查 null 或者零值

Checking for null or zero

在 JavaScript 中，1 或者任何非空对象都相当于 true。

In JavaScript, values of 1 or any non-null objects are treated as true.

// JavaScript
var myNull = null;
if (!myNull) {
  console.log('null is treated as false');
}
var zero = 0;
if (!zero) {
  console.log('0 is treated as false');
}

在 Dart 中，只有布尔类型值 true 才是 true。

In Dart, only the boolean value true is treated as true.

// Dart
var myNull = null;
if (myNull == null) {
  print('use "== null" to check null');
}
var zero = 0;
if (zero == 0) {
  print('use "== 0" to check zero');
}

可以在这里查看效果 DartPad。

Try it out in DartPad.

函数

Functions

Dart 和 JavaScript 中的函数很相似。最大的区别是声明格式。

Dart and JavaScript functions are generally similar. The primary difference is the declaration.

// JavaScript
function fn() {
  return true;
}

// Dart
fn() {
  return true;
}
// can also be written as
bool fn() {
  return true;
}

可以在这里查看效果 DartPad。

Try it out in DartPad.

如果想了解更多相关信息，请转向该页面 functions。

For more information, see the documentation on functions.

异步编程

Asynchronous programming

Futures

和 JavaScript 类似，Dart 支持单线程。在 JavaScript 中， Promise 对象代表异步操作的完成或者失败。

Like JavaScript, Dart supports single-threaded execution. In JavaScript, the Promise object represents the eventual completion (or failure) of an asynchronous operation and its resulting value.

Dart 使用 Future 对象来实现该机制。

Dart uses Future objects to handle this.

// JavaScript
class Example {
  _getIPAddress() {
    const url = 'https://httpbin.org/ip';
    return fetch(url)
      .then(response => response.json())
      .then(responseJson => {
        const ip = responseJson.origin;
        return ip;
      });
  }
}

function main() {
  const example = new Example();
  example
    ._getIPAddress()
    .then(ip => console.log(ip))
    .catch(error => console.error(error));
}

main();

// Dart
import 'dart:convert';
import 'package:http/http.dart' as http;

class Example {
  Future<String> _getIPAddress() {
    final url = new Uri.https('httpbin.org', '/ip');
    return http.get(url).then((response) {
      String ip = jsonDecode(response.body)['origin'];
      return ip;
    });
  }
}

main() {
  final example = new Example();
  example
      ._getIPAddress()
      .then((ip) => print(ip))
      .catchError((error) => print(error));
}

如果想了解更多相关信息，请参考 Future 的相关文档。

For more information, see the documentation on Future objects.

`async` 和 `await`

`async` and `await`

async 函数声明定义了一个异步函数。

The async function declaration defines an asynchronous function.

在 JavaScript 中， async 函数返回一个 Promise， await 操作符用于等待 Promise。

In JavaScript, the async function returns a Promise. The await operator is used to wait for a Promise.

// JavaScript
class Example {
  async function _getIPAddress() {
    const url = 'https://httpbin.org/ip';
    const response = await fetch(url);
    const json = await response.json();
    const data = json.origin;
    return data;
  }
}

async function main() {
  const example = new Example();
  try {
    const ip = await example._getIPAddress();
    console.log(ip);
  } catch (error) {
    console.error(error);
  }
}

main();

在 Dart 中，async 函数返回一个 Future，而函数体会在未来执行， await 操作符用于等待 Future。

In Dart, an async function returns a Future, and the body of the function is scheduled for execution later. The await operator is used to wait for a Future.

// Dart
import 'dart:convert';
import 'package:http/http.dart' as http;

class Example {
  Future<String> _getIPAddress() async {
    final url = new Uri.https('httpbin.org', '/ip');
    final response = await http.get(url);
    String ip = jsonDecode(response.body)['origin'];
    return ip;
  }
}

main() async {
  final example = new Example();
  try {
    final ip = await example._getIPAddress();
    print(ip);
  } catch (error) {
    print(error);
  }
}

如果想了解更多相关信息，请参考 async 和 await 的相关文档。

For more information, see the documentation for async and await.

基本知识

The basics

如何创建一个 Flutter 应用？

How do I create a Flutter app?

如果要使用 React Native 创建应用，你需要在命令行里运行 create-react-native-app。

To create an app using React Native, you would run create-react-native-app from the command line.

$ create-react-native-app <projectname>

要在 Flutter 中创建应用，完成下面其中一项即可：

To create an app in Flutter, do one of the following:

使用带有 Flutter 和 Dart 插件的 IDE。
Use an IDE with the Flutter and Dart plugins installed.
在命令行中运行命令 flutter create。不过要提前确认 Flutter SDK 已经在系统环境变量 PATH 中定义。
Use the flutter create command from the command line. Make sure that the Flutter SDK is in your PATH.

$ flutter create <projectname>

如果想要了解更多内容，详见开始使用 Flutter，在该页面会手把手教你创建一个点击按钮进行计数的应用。创建一个 Flutter 项目就可以构建 Android 和 iOS 设备上运行应用所需的所有文件。

For more information, see Getting started, which walks you through creating a button-click counter app. Creating a Flutter project builds all the files that you need to run a sample app on both Android and iOS devices.

我如何运行应用呢？

How do I run my app?

在 React Native, 你可以在项目文件夹中运行 npm run 或者 yarn run。

In React Native, you would run npm run or yarn run from the project directory.

你可以通过如下几个途径运行 Flutter 应用程序：

You can run Flutter apps in a couple of ways:

在带有 Flutter 和 Dart 插件的 IDE 中使用 “run” 选项。
Use the “run” option in an IDE with the Flutter and Dart plugins.
在项目根目录运行 flutter run。
Use flutter run from the project’s root directory.

你的应用程序会在已连接的设备、iOS 模拟器或者 Android 模拟器上运行。

Your app runs on a connected device, the iOS simulator, or the Android emulator.

如果想了解更多相关信息，可以参考 Flutter 的相关文档：开始使用 Flutter。

For more information, see the Flutter Getting Started documentation.

如何导入 widget

How do I import widgets?

在 React Native 中，你需要导入每一个所需的组件。

In React Native, you need to import each required component.

//React Native
import React from 'react';
import { StyleSheet, Text, View } from 'react-native';

在 Flutter 中，如果要使用 Material Design 库里的 widget，导入 material.dart 包。如果要使用 iOS 风格的 widget，导入 Cupertino 库。如果要使用更加基本的 widget，导入 Widgets 库。或者，你可以实现自己的 widget 库并导入。

In Flutter, to use widgets from the Material Design library, import the material.dart package. To use iOS style widgets, import the Cupertino library. To use a more basic widget set, import the Widgets library. Or, you can write your own widget library and import that.

import 'package:flutter/material.dart';
import 'package:flutter/cupertino.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter/my_widgets.dart';

无论你导入哪个库，Dart 仅仅引用你应用中用到的 widget。

Whichever widget package you import, Dart pulls in only the widgets that are used in your app.

如果想了解更多相关信息，可以参考核心 Widget 目录。

For more information, see the Flutter Widget Catalog.

在 Flutter 里有没有类似 React Native 中 “Hello world!” 应用程序？

What is the equivalent of the React Native “Hello world!” app in Flutter?

在 React Native，HelloWorldApp 继承自 React.Component 并且通过返回 view 对象实现了 render 方法。

In React Native, the HelloWorldApp class extends React.Component and implements the render method by returning a view component.

// React Native
import React from 'react';
import { StyleSheet, Text, View } from 'react-native';

export default class App extends React.Component {
  render() {
    return (
      <View style={styles.container}>
        <Text>Hello world!</Text>
      </View>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center'
  }
});

在 Flutter 中，你可以使用核心 widget 库中的 Center 和 Text widget 创建对应的 “Hello world!” 应用程序。 Center widget 是 widget 树中的根，而且只有 Text 一个子 widget。

In Flutter, you can create an identical “Hello world!” app using the Center and Text widgets from the core widget library. The Center widget becomes the root of the widget tree and has one child, the Text widget.

// Flutter
import 'package:flutter/material.dart';

void main() {
  runApp(
    Center(
      child: Text(
        'Hello, world!',
        textDirection: TextDirection.ltr,
      ),
    ),
  );
}

下面的图片展示了 Android 和 iOS 中的基本 Flutter “Hello world!” 应用程序的界面。

The following images show the Android and iOS UI for the basic Flutter “Hello world!” app.

现在大家已经明白了最基本的 Flutter 应用，接下来会告诉大家如何利用 Flutter 丰富的 widget 库来创建主流的华丽的应用程序。

Now that you’ve seen the most basic Flutter app, the next section shows how to take advantage of Flutter’s rich widget libraries to create a modern, polished app.

How do I use widgets and nest them to form a widget tree?

在 Flutter 中，几乎任何元素都是 widget。

In Flutter, almost everything is a widget.

widget 是构建应用软件用户界面的基本元素。你可以将 widget 按照一定的层次组合，成为 widget 树。每个 widget 内嵌在父 widget 中，并且继承了父 widget 的属性。甚至应用程序本身就是一个 widget。并没有一个独立的应用程序对象。反而 root widget 充当了这个角色。

Widgets are the basic building blocks of an app’s user interface. You compose widgets into a hierarchy, called a widget tree. Each widget nests inside a parent widget and inherits properties from its parent. Even the application object itself is a widget. There is no separate “application” object. Instead, the root widget serves this role.

一个 widget 可以定义：

A widget can define:

一个结构化的元素——类似按钮或者菜单
A structural element—like a button or menu
一个风格化的元素——类似字体或者颜色方案
A stylistic element—like a font or color scheme
布局元素——类似填充区或者对齐元素
An aspect of layout—like padding or alignment

下面的示例展示了使用 Material 库里 widget 实现的 “Hello world!” 应用程序。在这个示例中，该 widget 树是包含在 MaterialApp root widget 里的。

The following example shows the “Hello world!” app using widgets from the Material library. In this example, the widget tree is nested inside the MaterialApp root widget.

// Flutter
import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
 widget build(BuildContext context) {
    return MaterialApp(
      title: 'Welcome to Flutter',
      home: Scaffold(
        appBar: AppBar(
          title: Text('Welcome to Flutter'),
        ),
        body: Center(
          child: Text('Hello world'),
        ),
      ),
    );
  }
}

下面的图片为大家展示了通过 Material Design widget 所实现的 “Hello world!” 应用。你可以获得比 “Hello world!” 应用更多的功能。

The following images show “Hello world!” built from Material Design widgets. You get more functionality for free than in the basic “Hello world!” app.

当编写应用代码的时候，你将用到下述两种 widget：无状态 widget 就像它的名字一样，是一个没有状态的 widget。无状态 widget 一旦创建，就不会改变。而有状态 widget 会基于接收到的数据或者用户输入的数据动态改变状态。

When writing an app, you’ll use two types of widgets: StatelessWidget or StatefulWidget. A StatelessWidget is just what it sounds like—a widget with no state. A StatelessWidget is created once, and never changes its appearance. A StatefulWidget dynamically changes state based on data received, or user input.

无状态 widget 和有状态 widget 之间的主要区别，是有状态 widget 包含一个 State 对象会缓存状态数据，并且 widget 树的重建也会携带该数据，因此状态不会丢失。

The important difference between stateless and stateful widgets is that StatefulWidgets have a State object that stores state data and carries it over across tree rebuilds, so it’s not lost.

在简单的或者基本的应用程序中，封装 widget 非常简单，但是随着代码量的增加并且应用程序的功能变得更加复杂，你应该将层级复杂的 widget 封装到函数中或者稍小一些的类。创建独立的函数和 widget 可以让你更好地复用应用中组件。

In simple or basic apps it’s easy to nest widgets, but as the code base gets larger and the app becomes complex, you should break deeply nested widgets into functions that return the widget or smaller classes. Creating separate functions and widgets allows you to reuse the components within the app.

如何创建可复用的组件？

How do I create reusable components?

在 React Native 中，你可以定义一个类来创建一个可复用的组件然后使用 props 方法来设置或者返回属性或者所选元素的值。在下面的示例中，CustomCard 类在父类中被定义和调用。

In React Native, you would define a class to create a reusable component and then use props methods to set or return properties and values of the selected elements. In the example below, the CustomCard class is defined and then used inside a parent class.

// React Native
class CustomCard extends React.Component {
  render() {
    return (
      <View>
        <Text> Card {this.props.index} </Text>
        <Button
          title="Press"
          onPress={() => this.props.onPress(this.props.index)}
        />
      </View>
    );
  }
}

// Usage
<CustomCard onPress={this.onPress} index={item.key} />

在 Flutter 中，定义一个类来创建一个自定义 widget 然后复用这个 widget。你可以定义并且调用函数来返回一个可复用的 widget，正如下面示例中 build 函数所示的那样。

In Flutter, define a class to create a custom widget and then reuse the widget. You can also define and call a function that returns a reusable widget as shown in the build function in the following example.

// Flutter
class CustomCard extends StatelessWidget {
  CustomCard({@required this.index, @required
     this.onPress});

  final index;
  final Function onPress;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Column(
        children: <Widget>[
          Text('Card $index'),
          TextButton(
            child: const Text('Press'),
            onPressed: this.onPress,
          ),
        ],
      )
    );
  }
}
    ...
// Usage
CustomCard(
  index: index,
  onPress: () {
    print('Card $index');
  },
)
    ...

在之前的示例，CustomCard 类的构造函数使用 Dart 的曲括号 { } 来表示可选参数。

In the previous example, the constructor for the CustomCard class uses Dart’s curly brace syntax { } to indicate named optional parameters.

如果将这些参数设定为必填参数，要么从构造函数中删掉曲括号，或者在构造函数中加上 @required。

To require these fields, either remove the curly braces from the constructor, or add @required to the constructor.

下面的截图展示了可复用的 CustomCard 类的示例：

The following screenshots show an example of the reusable CustomCard class.

项目结构和资源

Project structure and resources

该从哪开始写代码呢？

Where do I start writing the code?

从 main.dart 文件开始。这个文件会在你创建 Flutter 应用时自动生成。

Start with the lib/main.dart file. It’s autogenerated when you create a Flutter app.

// Dart
void main(){
 print('Hello, this is the main function.');
}

在 Flutter 中，入口文件是 ’projectname’/lib/main.dart 而程序执行是从 main 函数开始的。

In Flutter, the entry point file is ’projectname’/lib/main.dart and execution starts from the main function.

Flutter 应用程序中的文件是如何组织的？

How are files structured in a Flutter app?

当你创建一个新的 Flutter 工程的时候，它会创建如下所示的文件夹结构。你可以自定义这个结构，不过这是整个开发的起点。

When you create a new Flutter project, it builds the following directory structure. You can customize it later, but this is where you start.

┬
└ projectname
  ┬
  ├ android      - Contains Android-specific files.
  ├ build        - Stores iOS and Android build files.
  ├ ios          - Contains iOS-specific files.
  ├ lib          - Contains externally accessible Dart source files.
    ┬
    └ src        - Contains additional source files.
    └ main.dart  - The Flutter entry point and the start of a new app.
                   This is generated automatically when you create a Flutter
                    project.
                   It's where you start writing your Dart code.
  ├ test         - Contains automated test files.
  └ pubspec.yaml - Contains the metadata for the Flutter app.
                   This is equivalent to the package.json file in React Native.

┬
└ projectname
  ┬
  ├ android      - 包含 Android 相关文件。
  ├ build        - 存储 iOS 和 Android 构建文件。
  ├ ios          - 包含 iOS 相关文件。
  ├ lib          - 包含外部可访问 Dart 源文件。
    ┬
    └ src        - 包含附加源文件。
    └ main.dart  - Flutter 程序入口和新应用程序的起点。当你创建 Flutter 工程的时候会自动生成这些文件。你从这里开始写 Dart 代码
  ├ test         - 包含自动测试文件。
  └ pubspec.yaml - 包含 Flutter 应用程序的元数据。这个文件相当于 React Native 里的 package.json 文件。

我该把资源文件放到哪并且如何调用呢？

Where do I put my resources and assets and how do I use them?

一个 Flutter 资源就是打包到你应用程序里的一个文件并且在程序运行的时候可以访问。 Flutter 应用程序可以包含下述几种资源类型：

A Flutter resource or asset is a file that is bundled and deployed with your app and is accessible at runtime. Flutter apps can include the following asset types:

类似 JSON 文件的静态数据
Static data such as JSON files
配置文件
Configuration files
图标和图片 (JPEG, PNG, GIF, Animated GIF, WebP, Animated WebP, BMP, and WBMP)
Icons and images (JPEG, PNG, GIF, Animated GIF, WebP, Animated WebP, BMP, and WBMP)

Flutter 使用 pubspec.yaml 文件来确定应用程序中的资源。该文件在工程的根目录。

Flutter uses the pubspec.yaml file, located at the root of your project, to identify assets required by an app.

flutter:
  assets:
    - assets/my_icon.png
    - assets/background.png

assets 确定了需要包含在应用程序中的文件。每个资源都会在 pubspec.yaml 中定义所存储的相对路径。资源定义的顺序没有特殊要求。实际的文件夹（在这里指 assets ）也没影响。但是，由于资源可以放置于程序的任何目录，所以放在 assets 文件夹是比较好的。

The assets subsection specifies files that should be included with the app. Each asset is identified by an explicit path relative to the pubspec.yaml file, where the asset file is located. The order in which the assets are declared does not matter. The actual directory used (assets in this case) does not matter. However, while assets can be placed in any app directory, it’s a best practice to place them in the assets directory.

在构建期间，Flutter 会将资源放到一个称为 asset bundle 的归档文件中，应用程序可以在运行时访问该文件。当一个资源在 pubspec.yaml 中被声明时，构建进程会查询和这个文件相关的子文件夹路径，这些文件也会被包含在 asset bundle 中。当你为应用程序选择和屏幕显示分辨率相关的图片时， Flutter 会使用 asset variants。

During a build, Flutter places assets into a special archive called the asset bundle, which apps read from at runtime. When an asset’s path is specified in the assets section of pubspec.yaml, the build process looks for any files with the same name in adjacent subdirectories. These files are also included in the asset bundle along with the specified asset. Flutter uses asset variants when choosing resolution-appropriate images for your app.

在 React Native，你可以在源码文件夹中通过添加文件来增加一个静态图片并且在代码中引用它。

In React Native, you would add a static image by placing the image file in a source code directory and referencing it.

<Image source={require('./my-icon.png')} />

在 Flutter 中，如果要增加静态图片的话就在 widget 的 build 方法中使用 AssetImage 类。

In Flutter, add a static image to your app using the AssetImage class in a widget’s build method.

image: AssetImage('assets/background.png'),

如果想了解更多相关信息，请参考文档在 Flutter 中添加资源和图片。

For more information, see Adding Assets and Images in Flutter.

如何在网络中加载图片？

How do I load images over a network?

在 React Native，你可以在 Image 的 source 属性中设置 uri 和所需的尺寸。

In React Native, you would specify the uri in the source prop of the Image component and also provide the size if needed.

在 Flutter 中，使用 Image.network 构造函数来实现通过地址加载图片的操作。

In Flutter, use the Image.network constructor to include an image from a URL.

// Flutter
body: Image.network(
          'https://flutter.io/images/owl.jpg',

我如何安装依赖包和包插件？

How do I install packages and package plugins?

Flutter 支持使用开发者向 Flutter 和 Dart 生态系统贡献的代码包。这样可以使大量开发者快速构建应用程序而无需重复造车轮。而平台相关的代码包就被称为包插件。

Flutter supports using shared packages contributed by other developers to the Flutter and Dart ecosystems. This allows you to quickly build your app without having to develop everything from scratch. Packages that contain platform-specific code are known as package plugins.

在 React Native 中，你可以在命令行中运行 yarn add {package-name} 或者 npm install --save {package-name} 来安装代码包。

In React Native, you would use yarn add {package-name} or npm install --save {package-name} to install packages from the command line.

在 Flutter 中，安装代码包需要按照如下的步骤：

In Flutter, install a package using the following instructions:

在 pubspec.yaml 的 dependencies 区域添加包名和版本。下面的例子向大家展示了如何将 google_sign_in 的 Dart package 添加到 pubspec.yaml 中。一定要检查一下 YAML 文件中的空格，因为 空格很重要!
Add the package name and version to the pubspec.yaml dependencies section. The example below shows how to add the google_sign_in Dart package to the pubspec.yaml file. Check your spaces when working in the YAML file because white space matters!

dependencies:
  flutter:
    sdk: flutter
  google_sign_in: ^3.0.3

在命令行中输入 flutter pub get 来安装代码包。如果使用 IDE，它自己会运行 flutter pub get，或者它会提示你是不是要运行该命令。
Install the package from the command line by using flutter pub get. If using an IDE, it often runs flutter pub get for you, or it might prompt you to do so.
向下面代码一样在程序中引用代码包：
Import the package into your app code as shown below:

import 'package:google_sign_in/google_sign_in.dart';

如果想了解更多相关信息，请参考在 Flutter 里使用 Packages 和 Flutter Packages 的开发和提交。

For more information, see Using Packages and Developing Packages & Plugins.

你可以找到很多 Flutter 开发者分享的代码包，就在 Flutter packages 的 pub.dev。

You can find many packages shared by Flutter developers in the Flutter packages section of the pub.dev.

Flutter widgets

在 Flutter 中，你可以基于 widget 打造你自己的 UI，通过 widget 当前的设置和状态会呈现相应的页面效果。

In Flutter, you build your UI out of widgets that describe what their view should look like given their current configuration and state.

Widget 常常通过很多小的、单一功能的 widget 组成，通过这样的封装往往能够实现很棒的效果。比如， Container widget 包含多种 widget，分别负责布局、绘图、位置变化和尺寸变化。准确的说，Container widget 包括 LimitedBox、ConstrainedBox、Align、 Padding、DecoratedBox 和 Transform widget。与其继承 Container 来实现自定义效果，不如直接修改这些 widget 来实现效果。

Widgets are often composed of many small, single-purpose widgets that are nested to produce powerful effects. For example, the Container widget consists of several widgets responsible for layout, painting, positioning, and sizing. Specifically, the Container widget includes the LimitedBox, ConstrainedBox, Align, Padding, DecoratedBox, and Transform widgets. Rather than subclassing Container to produce a customized effect, you can compose these and other simple widgets in new and unique ways.

Center widget 是另一个用于控制布局的示例。如果要居中一个 widget，就把它封装到 Center widget 中，然后使用布局 widget 来进行对齐行、列和网格。这些布局 widget 并不可见。而他们的作用就是控制其它 widget 的布局。如果想搞清楚为什么一个 widget 会有这样的效果，有效的方法是研究它临近的 widget。

The Center widget is another example of how you can control the layout. To center a widget, wrap it in a Center widget and then use layout widgets for alignment, row, columns, and grids. These layout widgets do not have a visual representation of their own. Instead, their sole purpose is to control some aspect of another widget’s layout. To understand why a widget renders in a certain way, it’s often helpful to inspect the neighboring widgets.

如果想了解更多相关信息，请参考技术概览。

For more information, see the Flutter Technical Overview.

如果想了解更多关于 Widgets 包中的核心 widget，请参考基础 Flutter Widgets、核心 Widget 目录或是 Flutter Widget 目录。

For more information about the core widgets from the Widgets package, see Flutter Basic Widgets, the Flutter Widget Catalog, or the Flutter Widget Index.

视图

Views

与 `View` 等价容器的是什么？

What is the equivalent of the `View` container?

在 React Native 中， View 是支持 Flexbox 布局、风格化、触摸事件处理和访问性控制的容器。

In React Native, View is a container that supports layout with Flexbox, style, touch handling, and accessibility controls.

在 Flutter 中，你可以使用 Widgets 库中的核心布局 widget，比如 Container、Column、Row 和 Center。如果想了解更多相关信息，请参考布局类 Widgets 目录。

In Flutter, you can use the core layout widgets in the Widgets library, such as Container, Column, Row, and Center. For more information, see the Layout Widgets catalog.

和 `FlatList` 或者 `SectionList` 相对应的是什么？

What is the equivalent of `FlatList` or `SectionList`?

List 是一个可以滚动的纵向排列的组件列表。

A List is a scrollable list of components arranged vertically.

在 React Native 中，FlatList 或者 SectionList 用于渲染简单的或者分组的列表。

In React Native, FlatList or SectionList are used to render simple or sectioned lists.

// React Native
<FlatList
  data={[ ... ]}
  renderItem={({ item }) => <Text>{item.key}</Text>}
/>

ListView 是 Flutter 最常用的滑动 widget。默认构造函数需要一个数据列表的参数。 ListView 非常适合用于少量子 widget 的列表。如果列表的元素比较多，可以使用 ListView.builder，它会按需构建子项并且只创建可见的子项。

ListView is Flutter’s most commonly used scrolling widget. The default constructor takes an explicit list of children. ListView is most appropriate for a small number of widgets. For a large or infinite list, use ListView.builder, which builds its children on demand and only builds those children that are visible.

// Flutter
var data = [ ... ];
ListView.builder(
  itemCount: data.length,
  itemBuilder: (context, int index) {
    return Text(
      data[index],
    );
  },
)

如果要了解如何实现无限滑动列表，请参考 Write Your First Flutter App, Part 1 的 codelab。

To learn how to implement an infinite scrolling list, see the Write Your First Flutter App, Part 1 codelab.

如何使用 Canvas 绘图？

How do I use a Canvas to draw or paint?

在 React Native 中，canvas 组件是不可见的，所以需要使用类似 react-native-canvas 这样的组件。

In React Native, canvas components aren’t present so third party libraries like react-native-canvas are used.

// React Native
handleCanvas = canvas => {
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'skyblue';
  ctx.beginPath();
  ctx.arc(75, 75, 50, 0, 2 * Math.PI);
  ctx.fillRect(150, 100, 300, 300);
  ctx.stroke();
};

render() {
  return (
    <View>
      <Canvas ref={this.handleCanvas} />
    </View>
  );
}

在 Flutter 中，你可以使用 CustomPaint 和 CustomPainter 在画布上进行绘制。

In Flutter, you can use the CustomPaint and CustomPainter classes to draw to the canvas.

下面的示例代码展示了如何使用 CustomPaint 进行绘图。它实现了抽象类 CustomPainter，然后将它赋值给 CustomPainter 的 painter 属性。 CustomPainter 子类必须实现 paint 和 shouldRepaint 方法。

The following example shows how to draw during the paint phase using the CustomPaint widget. It implements the abstract class, CustomPainter, and passes it to CustomPaint’s painter property. CustomPaint subclasses must implement the paint() and shouldRepaint() methods.

// Flutter
class MyCanvasPainter extends CustomPainter {

  @override
  void paint(Canvas canvas, Size size) {
    Paint paint = Paint();
    paint.color = Colors.amber;
    canvas.drawCircle(Offset(100.0, 200.0), 40.0, paint);
    Paint paintRect = Paint();
    paintRect.color = Colors.lightBlue;
    Rect rect = Rect.fromPoints(Offset(150.0, 300.0), Offset(300.0, 400.0));
    canvas.drawRect(rect, paintRect);
  }

  bool shouldRepaint(MyCanvasPainter oldDelegate) => false;
  bool shouldRebuildSemantics(MyCanvasPainter oldDelegate) => false;
}
class _MyCanvasState extends State<MyCanvas> {

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: CustomPaint(
        painter: MyCanvasPainter(),
      ),
    );
  }
}

布局

Layouts

如何使用 widget 来定义布局属性？

How do I use widgets to define layout properties?

在 React Native 中，大多数布局需要通过向指定的组件传递属性参数进行设置。比如，你可以使用 View 的 style 来设置 flexbox 属性。如果要整理一列的组件，你可以使用如下的属性设置：flexDirection: “column”。

In React Native, most of the layout can be done with the props that are passed to a specific component. For example, you could use the style prop on the View component in order to specify the flexbox properties. To arrange your components in a column, you would specify a prop such as: flexDirection: “column”.

// React Native
<View
  style={{
    flex: 1,
    flexDirection: 'column',
    justifyContent: 'space-between',
    alignItems: 'center'
  }}
>

在 Flutter 中，布局主要是由专门的 widget 定义的，它们同控制类 widget 和样式属性一起发挥功能。

In Flutter, the layout is primarily defined by widgets specifically designed to provide layout, combined with control widgets and their style properties.

比如，Column 和 Row widget 接受一个数组的子元素并且分别按照纵向和横向进行排列。 Container widget 包含布局和样式属性的组合， Center widget 会将其自 widget 也设定居中。

For example, the Column and Row widgets take an array of children and align them vertically and horizontally respectively. A Container widget takes a combination of layout and styling properties, and a Center widget centers its child widgets.

// Flutter
Center(
  child: Column(
    children: <Widget>[
      Container(
        color: Colors.red,
        width: 100.0,
        height: 100.0,
      ),
      Container(
        color: Colors.blue,
        width: 100.0,
        height: 100.0,
      ),
      Container(
        color: Colors.green,
        width: 100.0,
        height: 100.0,
      ),
    ],
  ),
)

Flutter 在核心 widget 库中提供多种不同的布局 widget。比如 Padding、Align 和 Stack。

Flutter provides a variety of layout widgets in its core widget library. For example, Padding, Align, and Stack.

要得到完整的 widget 列表，请参考 Layout Widgets。

For a complete list, see Layout Widgets.

如何为 widget 分层？

How do I layer widgets?

在 React Native 中，组件可以通过 absolute 划分层次。

In React Native, components can be layered using absolute positioning.

在 Flutter 中使用 Stack widget 将子 widget 进行分层。该 widget 可以将整体或者部分的子 widget 进行分层。

Flutter uses the Stack widget to arrange children widgets in layers. The widgets can entirely or partially overlap the base widget.

Stack widget 将子 widget 根据容器的边界进行布局。如果你仅仅想把子 widget 重叠摆放的话，这个 widget 非常合适。

The Stack widget positions its children relative to the edges of its box. This class is useful if you simply want to overlap several children widgets.

// Flutter
Stack(
  alignment: const Alignment(0.6, 0.6),
  children: <Widget>[
    CircleAvatar(
      backgroundImage: NetworkImage(
        'https://avatars3.githubusercontent.com/u/14101776?v=4'),
    ),
    Container(
      decoration: BoxDecoration(
          color: Colors.black45,
      ),
      child: Text('Flutter'),
    ),
  ],
)

上面的示例代码使用 Stack 将一个 Container （将 Text 显示在一个半透明的黑色背景上）覆盖在一个 CircleAvatar 上。Stack 使用对齐属性和 Alignment 坐标微调文本。

The previous example uses Stack to overlay a Container (that displays its Text on a translucent black background) on top of a CircleAvatar. The Stack offsets the text using the alignment property and Alignment coordinates.

如果想了解更多相关信息，请参考 Stack 类的文档。

For more information, see the Stack class documentation.

风格化

Styling

如何设置组件的风格？

How do I style my components?

在 React Native 中，内联风格化和 stylesheets.create 可以用于设置组件的风格。

In React Native, inline styling and stylesheets.create are used to style components.

// React Native
<View style={styles.container}>
  <Text style={{ fontSize: 32, color: 'cyan', fontWeight: '600' }}>
    This is a sample text
  </Text>
</View>

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center'
  }
});

在 Flutter 中， Text widget 可以接受 TextStyle 作为它的风格化属性。如果你想在不同的场合使用相同的文本风格，你可以创建一个 TextStyle 类，并且在多个 Text widget 中使用它。

In Flutter, a Text widget can take a TextStyle class for its style property. If you want to use the same text style in multiple places, you can create a TextStyle class and use it for multiple Text widgets.

// Flutter
var textStyle = TextStyle(fontSize: 32.0, color: Colors.cyan, fontWeight:
   FontWeight.w600);
	...
Center(
  child: Column(
    children: <Widget>[
      Text(
        'Sample text',
        style: textStyle,
      ),
      Padding(
        padding: EdgeInsets.all(20.0),
        child: Icon(Icons.lightbulb_outline,
          size: 48.0, color: Colors.redAccent)
      ),
    ],
  ),
)

我如何使用 `Icons` 和 `Colors` 呢？

How do I use `Icons` and `Colors`?

React Native 并不包含默认图标，所以需要使用第三方库。

React Native doesn’t include support for icons so third party libraries are used.

在 Flutter 中，引用 Material 库的时候就同时引入了 Material icons 和 colors。

In Flutter, importing the Material library also pulls in the rich set of Material icons and colors.

Icon(Icons.lightbulb_outline, color: Colors.redAccent)

当使用 Icons 类时，确保在项目的 pubspec.yaml 文件中设置 uses-material-design: true，这样保证 MaterialIcons 相关字体被包含在你的应用中。一般来说，如果你想用 Material 库的话，则需要包含这一行内容。

When using the Icons class, make sure to set uses-material-design: true in the project’s pubspec.yaml file. This ensures that the MaterialIcons font, which displays the icons, is included in your app. In general, if you intend to use the Material library, you should include this line.

name: my_awesome_application
flutter: uses-material-design: true

Flutter 的 Cupertino (iOS-style) package 为 iOS 设计语言提供高分辨率的 widget。要使用 CupertinoIcons 字体，在项目的 pubspec.yaml 文件中添加 cupertino_icons 的依赖即可。

Flutter’s Cupertino (iOS-style) package provides high fidelity widgets for the current iOS design language. To use the CupertinoIcons font, add a dependency for cupertino_icons in your project’s pubspec.yaml file.

name: my_awesome_application
dependencies:
  cupertino_icons: ^0.1.0

要在全局范围内自定义组件的颜色和风格，使用 ThemeData 为不同的主题指定默认颜色。在 MaterialApp 的主题属性中设置 ThemeData 对象。 Colors 类提供 Material Design color palette 中所提供的颜色配置。

To globally customize the colors and styles of components, use ThemeData to specify default colors for various aspects of the theme. Set the theme property in MaterialApp to the ThemeData object. The Colors class provides colors from the Material Design color palette.

下面的示例代码将主色调设置为 blue 然后文本颜色设置为 red。

The following example sets the primary swatch to blue and the text selection to red.

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
        textSelectionColor: Colors.red
      ),
      home: SampleAppPage(),
    );
  }
}

如何增加风格化主题？

How do I add style themes?

在 React Native，常用主题都定义在样式层叠表中。

In React Native, common themes are defined for components in stylesheets and then used in components.

在 Flutter 中，为所有组件创建统一风格可以在 ThemeData 类中定义，并将它赋值给 MaterialApp 的主题属性。

In Flutter, create uniform styling for almost everything by defining the styling in the ThemeData class and passing it to the theme property in the MaterialApp widget.

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        primaryColor: Colors.cyan,
        brightness: Brightness.dark,
      ),
      home: StylingPage(),
    );
  }

Theme 可以在不使用 MaterialApp widget 的情况下使用。 Theme 接受一个 ThemeData 参数，并且将 ThemeData 应用于它的全部子 widget。

A Theme can be applied even without using the MaterialApp widget. The Theme widget takes a ThemeData in its data parameter and applies the ThemeData to all of its children widgets.

  @override
  Widget build(BuildContext context) {
    return Theme(
      data: ThemeData(
        primaryColor: Colors.cyan,
        brightness: brightness,
      ),
      child: Scaffold(
         backgroundColor: Theme.of(context).primaryColor,
              ...
              ...
      ),
    );
  }

状态管理

State management

当 widget 被创建或者在 widget 的生命周期中有信息发生改变时所产生的信息叫做状态。要在 Flutter 中管理应用程序的状态，使用 StatefulWidget 和 State 对象。

State is information that can be read synchronously when a widget is built or information that might change during the lifetime of a widget. To manage app state in Flutter, use a StatefulWidget paired with a State object.

欲知更多关于 Flutter 的状态管理相关的内容，请参访状态管理文档页面。

For more information on ways to approach managing state in Flutter, see State management.

The StatelessWidget

StatelessWidget 在 Flutter 中是一个不需要状态改变的 widget，它没有内部的状态。

A StatelessWidget in Flutter is a widget that doesn’t require a state change—it has no internal state to manage.

当你展现给用户的界面并不依赖其它任何配置信息并且使用 BuildContext 来解析 widget，则需要使用无状态 widget。

Stateless widgets are useful when the part of the user interface you are describing does not depend on anything other than the configuration information in the object itself and the BuildContext in which the widget is inflated.

AboutDialog、CircleAvatar 和 Text 是 StatelessWidget 的子类，并且是很典型的无状态 widget。

AboutDialog, CircleAvatar, and Text are examples of stateless widgets that subclass StatelessWidget.

// Flutter
import 'package:flutter/material.dart';

void main() => runApp(MyStatelessWidget(text: 'StatelessWidget Example to show immutable data'));

class MyStatelessWidget extends StatelessWidget {
  final String text;
  MyStatelessWidget({Key key, this.text}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Text(
        text,
        textDirection: TextDirection.ltr,
      ),
    );
  }
}

在上面的例子中，你用到了 MyStatelessWidget 类的构造函数来传递 text。并且它被标记为 final。该类继承了 StatelessWidget，它包含不可变的数据。

The previous example uses the constructor of the MyStatelessWidget class to pass the text, which is marked as final. This class extends StatelessWidget—it contains immutable data.

无状态 widget 的 build 方法通常只有在三种情况下会被调用：

The build method of a stateless widget is typically called in only three situations:

当 widget 被插入到 widget 树中；
When the widget is inserted into a tree
当 widget 的父 widget 改变了配置；
When the widget’s parent changes its configuration
当所依赖的 InheritedWidget 发生了改变。
When an InheritedWidget it depends on, changes

The StatefulWidget

StatefulWidget 是携带状态变化的 widget。通过调用 setState 方法可以管理 StatefulWidget 的状态。当调用 setState() 的时候，程序会通知 Flutter 框架有状态发生了改变，然后会重新运行 build() 方法来更新应用的状态。

A StatefulWidget is a widget that changes state. Use the setState method to manage the state changes for a StatefulWidget. A call to setState() tells the Flutter framework that something has changed in a state, which causes an app to rerun the build() method so that the app can reflect the change.

状态是在 widget 被创建期间可以被同步读取的信息，并且在 widget 的生命周期中会发生改变。实现该 widget 的时候要注意保证党状态发生改变的时候程序能够获得相应的提醒。当 widget 能够动态改变的时候，请使用 StatefulWidget。比如，某个 widget 会随着用户填写表单或者移动滑块的时候发生改变。亦或者随着数据源更新的时候发生改变。

State is information that can be read synchronously when a widget is built and might change during the lifetime of the widget. It’s the responsibility of the widget implementer to ensure that the state object is promptly notified when the state changes. Use StatefulWidget when a widget can change dynamically. For example, the state of the widget changes by typing into a form, or moving a slider. Or, it can change over time—perhaps a data feed updates the UI.

Checkbox、Radio、Slider、InkWell、 Form、和 TextField 都是有状态的 widget，是 StatefulWidget 的子类。

Checkbox, Radio, Slider, InkWell, Form, and TextField are examples of stateful widgets that subclass StatefulWidget.

下面的示例代码声明了一个 StatefulWidget，需要实现 createState() 方法。该方法创建一个对象来管理 widget 的状态，也就是 _MyStatefulWidgetState。

The following example declares a StatefulWidget that requires a createState() method. This method creates the state object that manages the widget’s state, _MyStatefulWidgetState.

class MyStatefulWidget extends StatefulWidget {
  MyStatefulWidget({Key key, this.title}) : super(key: key);
  final String title;

  @override
  _MyStatefulWidgetState createState() => _MyStatefulWidgetState();
}

下面的状态类，_MyStatefulWidgetState，实现了 build() 方法。当状态发生改变的时候，比如说用户点击了开关按钮，这时 setState 就会被调用，并且将新的开关状态传进来。这就会使整体框架重构这个 widget。

The following state class, _MyStatefulWidgetState, implements the build() method for the widget. When the state changes, for example, when the user toggles the button, setState() is called with the new toggle value. This causes the framework to rebuild this widget in the UI.

class _MyStatefulWidgetState extends State<MyStatefulWidget> {
  bool showtext=true;
  bool toggleState=true;
  Timer t2;

  void toggleBlinkState(){
    setState((){
      toggleState=!toggleState;
    });
    var twenty = const Duration(milliseconds: 1000);
    if(toggleState==false) {
      t2 = Timer.periodic(twenty, (Timer t) {
        toggleShowText();
      });
    } else {
      t2.cancel();
    }
  }

  void toggleShowText(){
    setState((){
      showtext=!showtext;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          children: <Widget>[
            (showtext
              ?(Text('This execution will be done before you can blink.'))
              :(Container())
            ),
            Padding(
              padding: EdgeInsets.only(top: 70.0),
              child: ElevatedButton(
                onPressed: toggleBlinkState,
                child: (toggleState
                  ?( Text('Blink'))
                  :(Text('Stop Blinking'))
                )
              )
            )
          ],
        ),
      ),
    );
  }
}

StatefulWidget 和 StatelessWidget 的最佳实践是什么？

What are the StatefulWidget and StatelessWidget best practices?

下面有一些设计原则供大家参考。

Here are a few things to consider when designing your widget.

确定一个 widget 应该是 StatefulWidget 还是 StatelessWidget
Determine whether a widget should be a StatefulWidget or a StatelessWidget

在 Flutter 中， widget 要么是有状态的，要么是无状态的。这取决于 widget 是否依赖状态的改变。

In Flutter, widgets are either Stateful or Stateless—depending on whether they depend on a state change.

如果一个 widget 发生了改变，而它所处的用户界面或者数据中断了 UI，那么该 widget 就是有状态的。
If a widget changes—the user interacts with it or a data feed interrupts the UI, then it’s Stateful.
如果一个 widget 是 final 类型或者 immutable 类型的，那么该 widget 是无状态的。
If a widget is final or immutable, then it’s Stateless.

确定哪个对象来控制 widget 的状态（针对 StatefulWidget）。
Determine which object manages the widget’s state (for a StatefulWidget)

在 Flutter 中，有三种途径来管理状态：

In Flutter, there are three primary ways to manage state:

widget 管理它的自身状态
The widget manages its own state
由其父 widget 管理 widget 状态
The parent widget manages the widget’s state
通过混搭的方式
A mix-and-match approach

当决定了使用哪个途径后，要考虑下述的几个原则：

When deciding which approach to use, consider the following principles:

如果状态信息是用户数据，比如 checkbox 是被勾选还是未被勾选，或者滑块的位置，那么父 widget 会很好的处理当前 widget 的状态。
If the state in question is user data, for example the checked or unchecked mode of a checkbox, or the position of a slider, then the state is best managed by the parent widget.
如果状态是和外观效果相关的，比如动画，那么 widget 自己会处理状态的变化。
If the state in question is user data, for example the checked or unchecked mode of a checkbox, or the position of a slider, then the state is best managed by the parent widget.
如果无法确定，那么父 widget 会处理子 widget 的状态。
When in doubt, let the parent widget manage the child widget’s state.

继承 StatefulWidget 和状态
Subclass StatefulWidget and State.

MyStatefulWidget 类管理它自身的状态—&mdash它继承自 StatefulWidget，重写了 createState() 方法。该方法创建了 State 对象，同时框架会调用 createState() 方法来构建 widget。在这个例子中，createState() 方法创建了一个 _MyStatefulWidgetState 实例。下面的最佳实践中也实现了类似的方法。

The MyStatefulWidget class manages its own state—it extends StatefulWidget, it overrides the createState() method to create the State object, and the framework calls createState() to build the widget. In this example, createState() creates an instance of _MyStatefulWidgetState, which is implemented in the next best practice.

class MyStatefulWidget extends StatefulWidget {
  MyStatefulWidget({Key key, this.title}) : super(key: key);
  final String title;

  @override
  _MyStatefulWidgetState createState() => _MyStatefulWidgetState();
}

class _MyStatefulWidgetState extends State<MyStatefulWidget> {

  @override
  Widget build(BuildContext context) {
    ...
  }
}

将 StatefulWidget 添加到 widget 树中
Add the StatefulWidget into the widget tree.

将你自定义的 StatefulWidget 通过应用程序的 build 方法添加到 widget 树中。

Add your custom StatefulWidget to the widget tree in the app’s build method.

class MyStatelessWidget extends StatelessWidget {
  // This widget is the root of your application.

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyStatefulWidget(title: 'State Change Demo'),
    );
  }
}

Props

在 React Native 中，大多数组件都可以在创建的时候通过不同的参数或者属性来自定义，叫做 props。这些参数可以在子组件中通过 this.props 进行调用。

In React Native, most components can be customized when they are created with different parameters or properties, called props. These parameters can be used in a child component using this.props.

// React Native
class CustomCard extends React.Component {
  render() {
    return (
      <View>
        <Text> Card {this.props.index} </Text>
        <Button
          title='Press'
          onPress={() => this.props.onPress(this.props.index)}
        />
      </View>
    );
  }
}
class App extends React.Component {

  onPress = index => {
    console.log('Card ', index);
  };

  render() {
    return (
      <View>
        <FlatList
          data={[ ... ]}
          renderItem={({ item }) => (
            <CustomCard onPress={this.onPress} index={item.key} />
          )}
        />
      </View>
    );
  }
}

在 Flutter 中，你可以将构造函数中的参数值赋值给标记为 final 的本地变量或者函数。

In Flutter, you assign a local variable or function marked final with the property received in the parameterized constructor.

// Flutter
class CustomCard extends StatelessWidget {

  CustomCard({@required this.index, @required this.onPress});
  final index;
  final Function onPress;

  @override
  Widget build(BuildContext context) {
  return Card(
    child: Column(
      children: <Widget>[
        Text('Card $index'),
        TextButton(
          child: const Text('Press'),
          onPressed: this.onPress,
        ),
      ],
    ));
  }
}
    ...
//Usage
CustomCard(
  index: index,
  onPress: () {
    print('Card $index');
  },
)

本地存储

Local storage

如果你不需要在本地存储太多数据同时也不需要存储结构化数据，那么你可以使用 shared_preferences，通过它来读写一些原始数据类型键值对，数据类型包括 boolean、float、ints、longs 和 string。

If you don’t need to store a lot of data and it doesn’t require structure, you can use shared_preferences which allows you to read and write persistent key-value pairs of primitive data types: booleans, floats, ints, longs, and strings.

如何存储在应用程序中全局有效的键值对？

How do I store persistent key-value pairs that are global to the app?

在 React Native，可以使用 AsyncStorage 中的 setItem 和 getItem 函数来存储和读取应用程序中的全局数据。

In React Native, you use the setItem and getItem functions of the AsyncStorage component to store and retrieve data that is persistent and global to the app.

// React Native
await AsyncStorage.setItem( 'counterkey', json.stringify(++this.state.counter));
AsyncStorage.getItem('counterkey').then(value => {
  if (value != null) {
    this.setState({ counter: value });
  }
});

在 Flutter 中，使用 shared_preferences 插件来存储和访问应用程序内全局有效的键值对数据。 shared_preferences 插件封装了 iOS 中的 NSUserDefaults 和 Android 中的 SharedPreferences 来实现简单数据的持续存储。如果要使用该插件，可以在 pubspec.yaml 中添加依赖 shared_preferences，然后在 Dart 文件中引用包即可。

In Flutter, use the shared_preferences plugin to store and retrieve key-value data that is persistent and global to the app. The shared_preferences plugin wraps NSUserDefaults on iOS and SharedPreferences on Android, providing a persistent store for simple data. To use the plugin, add shared_preferences as a dependency in the pubspec.yaml file then import the package in your Dart file.

dependencies:
  flutter:
    sdk: flutter
  shared_preferences: ^0.4.3

// Dart
import 'package:shared_preferences/shared_preferences.dart';

要实现持久数据存储，使用 SharedPreferences 类提供的 setter 方法即可。 Setter 方法适用于多种原始类型数据，比如 setInt, setBool, 和 setString。要读取数据，使用 SharedPreferences 类中相应的 getter 方法。每一个 setter 方法都有对应的 getter 方法，比如，getInt, getBool, 和 getString。

To implement persistent data, use the setter methods provided by the SharedPreferences class. Setter methods are available for various primitive types, such as setInt, setBool, and setString. To read data, use the appropriate getter method provided by the SharedPreferences class. For each setter there is a corresponding getter method, for example, getInt, getBool, and getString.

SharedPreferences prefs = await SharedPreferences.getInstance();
_counter = prefs.getInt('counter');
prefs.setInt('counter', ++_counter);
setState(() {
  _counter = _counter;
});

路径

Routing

大多数应用都会包含多个页面来显示不同类型的数据。比如，你有一个页面展示商品列表，用户可以通过点击其中的任意一个商品，在另外一个页面查看该商品的详细信息。

Most apps contain several screens for displaying different types of information. For example, you might have a product screen that displays images where users could tap on a product image to get more information about the product on a new screen.

在 Android 中，新的页面是 Activity。在 iOS 中，新的页面是 ViewController。在 Flutter 中，页面也只是 widget，如果在 Flutter 中要切换页面，使用 Navigator widget 即可。

In Android, new screens are new Activities. In iOS, new screens are new ViewControllers. In Flutter, screens are just Widgets! And to navigate to new screens in Flutter, use the Navigator widget.

如何在页面之间进行切换？

How do I navigate between screens?

在 React Native，有三种主要的导航 widget ： StackNavigator、TabNavigator 和 DrawerNavigator。每个都提供了配置和定义页面的方法。

In React Native, there are three main navigators: StackNavigator, TabNavigator, and DrawerNavigator. Each provides a way to configure and define the screens.

// React Native
const MyApp = TabNavigator(
  { Home: { screen: HomeScreen }, Notifications: { screen: tabNavScreen } },
  { tabBarOptions: { activeTintColor: '#e91e63' } }
);
const SimpleApp = StackNavigator({
  Home: { screen: MyApp },
  stackScreen: { screen: StackScreen }
});
export default (MyApp1 = DrawerNavigator({
  Home: {
    screen: SimpleApp
  },
  Screen2: {
    screen: drawerScreen
  }
}));

在 Flutter 中，有两种主要的 widget 实现页面之间的切换：

In Flutter, there are two main widgets used to navigate between screens:

Route 是应用程序页面的一个抽象类。
A Route is an abstraction for an app screen or page.
Navigator 是管理页面路径的 widget。
A Navigator is a widget that manages routes.

Navigator 以堆栈的方式管理子 widget。它的堆栈里存储的是 Route 对象，并且提供方法管理整个堆栈，比如 Navigator.push 和 Navigator.pop。路径列表需要在 MaterialApp 中指定。或者在页面切换的时候进行构建，比如 hero 动画。下面的例子在 MaterialApp widget 中指定了页面切换路径。

A Navigator is defined as a widget that manages a set of child widgets with a stack discipline. The navigator manages a stack of Route objects and provides methods for managing the stack, like Navigator.push and Navigator.pop. A list of routes might be specified in the MaterialApp widget, or they might be built on the fly, for example, in hero animations. The following example specifies named routes in the MaterialApp widget.

// Flutter
class NavigationApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
            ...
      routes: <String, WidgetBuilder>{
        '/a': (BuildContext context) => usualNavscreen(),
        '/b': (BuildContext context) => drawerNavscreen(),
      }
            ...
  );
  }
}

要切换到一个已命名的路径，Navigator.of() 方法被用于指定 BuildContext（该对象可以定位到 widget 树中的一个具体的 widget）。路径的名称传递到 pushNamed 函数来切换至指定的路径。

To navigate to a named route, the Navigator.of() method is used to specify the BuildContext (a handle to the location of a widget in the widget tree). The name of the route is passed to the pushNamed function to navigate to the specified route.

Navigator.of(context).pushNamed('/a');

你可以使用 Navigator 中的 push 方法添加 Route 到 navigator 的历史队列中，其中包含 BuildContext 并且可以切换到指定页面。在下面的例子中，MaterialPageRoute widget 是一个模式化路径，可以将整个页面通过平台自适应切换方式进行切换。它需要一个 WidgetBuilder 参数。

You can also use the push method of Navigator which adds the given Route to the history of the navigator that most tightly encloses the given BuildContext, and transitions to it. In the following example, the MaterialPageRoute widget is a modal route that replaces the entire screen with a platform-adaptive transition. It takes a WidgetBuilder as a required parameter.

Navigator.push(context, MaterialPageRoute(builder: (BuildContext context)
 => UsualNavscreen()));

How do I use tab navigation and drawer navigation?

在 Material Design 应用程序中，Flutter 的导航形式主要有两种：tab 和 drawer。如果没有足够的 widget 可以容纳 tab，drawer 就是个不错的选择。

In Material Design apps, there are two primary options for Flutter navigation: tabs and drawers. When there is insufficient space to support tabs, drawers provide a good alternative.

Tab navigation

在 React Native 中，createBottomTabNavigator 和 TabNavigation 用来显示 tab 和 tab 导航。

In React Native, createBottomTabNavigator and TabNavigation are used to show tabs and for tab navigation.

// React Native
import { createBottomTabNavigator } from 'react-navigation';

const MyApp = TabNavigator(
  { Home: { screen: HomeScreen }, Notifications: { screen: tabNavScreen } },
  { tabBarOptions: { activeTintColor: '#e91e63' } }
);

Flutter 针对 drawer 和 tab 导航提供几种专用的 widget：

Flutter provides several specialized widgets for drawer and tab navigation:

TabController——将 tab 与 TabBar 和 TabBarView 结合起来使用。
TabController—Coordinates the tab selection between a TabBar and a TabBarView.
TabBar——水平显示一行 tab。
TabBar—Displays a horizontal row of tabs.
Tab——创建一个 material design 风格的 TabBar 中的 tab。
Tab—Creates a material design TabBar tab.
TabBarView——显示目前所选 tab 所对应的 widget。
TabBarView—Displays the widget that corresponds to the currently selected tab.

// Flutter
TabController controller=TabController(length: 2, vsync: this);

TabBar(
  tabs: <Tab>[
    Tab(icon: Icon(Icons.person),),
    Tab(icon: Icon(Icons.email),),
  ],
  controller: controller,
),

要将 tab 选项与 TabBar 和 TabBarView 结合起来使用就需要 TabController。 TabController 的构造函数中的 length 参数定义了 tab 的总数。当状态变化时，需要使用 TickerProvider 来触发通知。 TickerProvider 是 vsync，当你需要创建新的 TabController 时，将 vsync: this 作为构造函数的参数即可。

A TabController is required to coordinate the tab selection between a TabBar and a TabBarView. The TabController constructor length argument is the total number of tabs. A TickerProvider is required to trigger the notification whenever a frame triggers a state change. The TickerProvider is vsync. Pass the vsync: this argument to the TabController constructor whenever you create a new TabController.

TickerProvider 接口可以用于生成 Ticker 对象。当有对象被触发通知后会用到 Tickers，不过它通常都是被 AnimationController 间接调用。 AnimationControllers 需要 TickerProvider 来获得对应的 Ticker。如果你通过 State 创建了一个 AnimationController，那么你就可以使用 TickerProviderStateMixin 或者 SingleTickerProviderStateMixin 来获得对应的 TickerProvider。

The TickerProvider is an interface implemented by classes that can vend Ticker objects. Tickers can be used by any object that must be notified whenever a frame triggers, but they’re most commonly used indirectly via an AnimationController. AnimationControllers need a TickerProvider to obtain their Ticker. If you are creating an AnimationController from a State, then you can use the TickerProviderStateMixin or SingleTickerProviderStateMixin classes to obtain a suitable TickerProvider.

Scaffold 封装了一个新的 TabBar widget，其中包含两个 tab。 TabBarView 作为 body 参数传递到 Scaffold 中。所有和 TabBar 中的 tab 相关的页面均是 TabBarView 的子 widget，并且都对应同一个 TabController。

The Scaffold widget wraps a new TabBar widget and creates two tabs. The TabBarView widget is passed as the body parameter of the Scaffold widget. All screens corresponding to the TabBar widget’s tabs are children to the TabBarView widget along with the same TabController.

// Flutter

class _NavigationHomePageState extends State<NavigationHomePage> with SingleTickerProviderStateMixin {
  TabController controller=TabController(length: 2, vsync: this);
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      bottomNavigationBar: Material (
        child: TabBar(
          tabs: <Tab> [
            Tab(icon: Icon(Icons.person),)
            Tab(icon: Icon(Icons.email),),
          ],
          controller: controller,
        ),
        color: Colors.blue,
      ),
      body: TabBarView(
        children: <Widget> [
          home.homeScreen(),
          tabScreen.tabScreen()
        ],
        controller: controller,
      )
    );
  }
}

Drawer navigation

在 React Native 中，导入所需的 react-navigation 包，然后使用 createDrawerNavigator 和 DrawerNavigation 实现。

In React Native, import the needed react-navigation packages and then use createDrawerNavigator and DrawerNavigation.

// React Native
export default (MyApp1 = DrawerNavigator({
  Home: {
    screen: SimpleApp
  },
  Screen2: {
    screen: drawerScreen
  }
}));

在 Flutter 中，我们可以结合 Drawer 和 Scaffold 一起使用来实现 Material Design 风格的 drawer 布局。如果要在应用程序中添加 Drawer，可以将它封装在 Scaffold widget 中。 Scaffold widget 提供了一种一致的界面风格，它遵循 Material Design 的设计原则。同时它还支持一些特殊的 Material Design 组件，比如 Drawers，AppBars，和 SnackBars。

In Flutter, we can use the Drawer widget in combination with a Scaffold to create a layout with a Material Design drawer. To add a Drawer to an app, wrap it in a Scaffold widget. The Scaffold widget provides a consistent visual structure to apps that follow the Material Design guidelines. It also supports special Material Design components, such as Drawers, AppBars, and SnackBars.

Drawer 就是一个 Material Design 窗格，它可以从 Scaffold 边缘水平滑动显示应用程序的导航选项。你可以在里面添加 ElevatedButton 或 Text 。或者添加一个列表的元素作为 Drawer 的子 widget。在下面的例子中，ListTile 提供了点击导航。

The Drawer widget is a Material Design panel that slides in horizontally from the edge of a Scaffold to show navigation links in an application. You can provide a ElevatedButton, a Text widget, or a list of items to display as the child to the Drawer widget. In the following example, the ListTile widget provides the navigation on tap.

// Flutter
Drawer(
  child:ListTile(
    leading: Icon(Icons.change_history),
    title: Text('Screen2'),
    onTap: () {
      Navigator.of(context).pushNamed('/b');
    },
  ),
  elevation: 20.0,
),

Scaffold 还包含一个 AppBar。它会自动显示一个图标按钮来表明 Scaffold 中有一个Drawer。 Scaffold 会自动处理边缘的滑动手势来显示 Drawer。

The Scaffold widget also includes an AppBar widget that automatically displays an appropriate IconButton to show the Drawer when a Drawer is available in the Scaffold. The Scaffold automatically handles the edge-swipe gesture to show the Drawer.

// Flutter
@override
Widget build(BuildContext context) {
  return Scaffold(
    drawer: Drawer(
      child: ListTile(
        leading: Icon(Icons.change_history),
        title: Text('Screen2'),
        onTap: () {
          Navigator.of(context).pushNamed('/b');
        },
      ),
      elevation: 20.0,
    ),
    appBar: AppBar(
      title: Text('Home'),
    ),
    body: Container(),
  );
}

手势检测和触摸事件处理

Gesture detection and touch event handling

Flutter 支持点击、拖拽和缩放手势来监听和相应手势操作。 Flutter 中的手势处理有两个独立的层。第一层是指针事件，指针事件定义了指针在屏幕上的位置和动作，比如触摸、鼠标和触摸笔。第二层指手势，主要是语义层面的动作，里面包含一种或者多种指针动作。

To listen for and respond to gestures, Flutter supports taps, drags, and scaling. The gesture system in Flutter has two separate layers. The first layer includes raw pointer events, which describe the location and movement of pointers, (such as touches, mice, and styli movements), across the screen. The second layer includes gestures, which describe semantic actions that consist of one or more pointer movements.

How do I add a click or press listeners to a widget?

在 React Native 中，使用 PanResponder 或者 Touchable 组件来添加监听器。

In React Native, listeners are added to components using PanResponder or the Touchable components.

// React Native
<TouchableOpacity
  onPress={() => {
    console.log('Press');
  }}
  onLongPress={() => {
    console.log('Long Press');
  }}
>
  <Text>Tap or Long Press</Text>
</TouchableOpacity>

对于更加复杂手势以及将多个触摸添加到单独的一个手势中，可以使用 PanResponder。

For more complex gestures and combining several touches into a single gesture, PanResponder is used.

// React Native
class App extends Component {

  componentWillMount() {
    this._panResponder = PanResponder.create({
      onMoveShouldSetPanResponder: (event, gestureState) =>
        !!getDirection(gestureState),
      onPanResponderMove: (event, gestureState) => true,
      onPanResponderRelease: (event, gestureState) => {
        const drag = getDirection(gestureState);
      },
      onPanResponderTerminationRequest: (event, gestureState) => true
    });
  }

  render() {
    return (
      <View style={styles.container} {...this._panResponder.panHandlers}>
        <View style={styles.center}>
          <Text>Swipe Horizontally or Vertically</Text>
        </View>
      </View>
    );
  }
}

在 Flutter 中，要为 widget 添加点击或者按压监听器，使用带有 onPress: field 的按钮或者可触摸 widget 即可。或者，用任何 widget 封装 GestureDetector，在其中添加手势检测。

In Flutter, to add a click (or press) listener to a widget, use a button or a touchable widget that has an onPress: field. Or, add gesture detection to any widget by wrapping it in a GestureDetector.

// Flutter
GestureDetector(
  child: Scaffold(
    appBar: AppBar(
      title: Text('Gestures'),
    ),
    body: Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: <Widget>[
          Text('Tap, Long Press, Swipe Horizontally or Vertically '),
        ],
      )
    ),
  ),
  onTap: () {
    print('Tapped');
  },
  onLongPress: () {
    print('Long Pressed');
  },
  onVerticalDragEnd: (DragEndDetails value) {
    print('Swiped Vertically');
  },
  onHorizontalDragEnd: (DragEndDetails value) {
    print('Swiped Horizontally');
  },
);

如果想要了解更多详细内容，包括 Flutter 的 GestureDetector 回调函数的列表，请查看页面 GestureDetector 类。

For more information, including a list of Flutter GestureDetector callbacks, see the GestureDetector class.

发起 HTTP 网络请求

Making HTTP network requests

对于大多数应用程序来说都需要从互联网上获取数据。在 Flutter 中，http 包提供了从互联网获取数据的最简单的途径。

Fetching data from the internet is common for most apps. And in Flutter, the http package provides the simplest way to fetch data from the internet.

如何通过 API 调用来获得数据呢？

How do I fetch data from API calls?

React Native 提供 Fetch API 实现网络编程，你可以发起请求，然后接收响应来获得数据。

React Native provides the Fetch API for networking—you make a fetch request and then receive the response to get the data.

// React Native
_getIPAddress = () => {
  fetch('https://httpbin.org/ip')
    .then(response => response.json())
    .then(responseJson => {
      this.setState({ _ipAddress: responseJson.origin });
    })
    .catch(error => {
      console.error(error);
    });
};

Flutter 使用 http 包。如果要安装 http 包，将它添加到 pubspec.yaml 的 dependencies 部分。

Flutter uses the http package. To install the http package, add it to the dependencies section of our pubspec.yaml.

dependencies:
  flutter:
    sdk: flutter
  http: <latest_version>

Flutter 使用 dart:io 提供核心的 HTTP 客户端支持，要创建一个 HTTP 客户端，引用 dart:io。

Flutter uses the dart:io core HTTP support client. To create an HTTP Client, import dart:io.

import 'dart:io';

客户端支持如下所列的 HTTP 操作：GET, POST, PUT 和 DELETE。

The client supports the following HTTP operations: GET, POST, PUT, and DELETE.

// Flutter
final url = Uri.parse('https://httpbin.org/ip');
final httpClient = HttpClient();
_getIPAddress() async {
  var request = await httpClient.getUrl(url);
  var response = await request.close();
  var responseBody = await response.transform(utf8.decoder).join();
  String ip = jsonDecode(responseBody)['origin'];
  setState(() {
    _ipAddress = ip;
  });
}

输入表单

Form input

TextField 用于在应用程序中输入文本，这样就可以实现创建表单、短消息应用、搜索框等等功能。Flutter 提供两个核心文本输入 widget： TextField 和 TextFormField.

Text fields allow users to type text into your app so they can be used to build forms, messaging apps, search experiences, and more. Flutter provides two core text field widgets: TextField and TextFormField.

如何使用文本输入 widget ？

How do I use text field widgets?

在 React Native 里，可以使用 TextInput 组件来输入文本，它会显示一个输入框，然后通过回调函数来传递输入值。

In React Native, to enter text you use a TextInput component to show a text input box and then use the callback to store the value in a variable.

// React Native
<TextInput
  placeholder="Enter your Password"
  onChangeText={password => this.setState({ password })}
 />
<Button title="Submit" onPress={this.validate} />

在 Flutter 中，使用 TextEditingController 类来管理 TextField widget。当用户修改文本的时候，controller 会通知监听器。

In Flutter, use the TextEditingController class to manage a TextField widget. Whenever the text field is modified, the controller notifies its listeners.

监听器读取文本和选项属性来获知用户所输入的内容。你可以通过 TextField 中的 text 属性获得用户输入的文本数据。

Listeners read the text and selection properties to learn what the user typed into the field. You can access the text in TextField by the text property of the controller.

// Flutter
final TextEditingController _controller = TextEditingController();
      ...
TextField(
  controller: _controller,
  decoration: InputDecoration(
    hintText: 'Type something', labelText: 'Text Field '
  ),
),
ElevatedButton(
  child: Text('Submit'),
  onPressed: () {
    showDialog(
      context: context,
        child: AlertDialog(
          title: Text('Alert'),
          content: Text('You typed ${_controller.text}'),
        ),
     );
   },
 ),
)

在这个例子中，当用户点击提交按钮的时候，会弹出窗口显示当前输入的文本内容。可以使用 alertDialog widget 显示提示信息， TextField 的文本通过 text 属性来获得，该属性属于 TextEditingController。

In this example, when a user clicks on the submit button an alert dialog displays the current text entered in the text field. This is achieved using an alertDialog widget that displays the alert message, and the text from the TextField is accessed by the text property of the TextEditingController.

如何使用 Form widget 呢？

How do I use Form widgets?

在 Flutter 中，当需要使用带有提交按钮和 TextFormField 组件的复合 widget 时，就会用到 Form。 TextFormField 内含一个 onSaved 参数，它可以设置一个回调函数，当表单存储的时候会回调该函数。 FormState 用于存储、重置或者验证 Form 内含的每个 FormField。你可以通过将当前表单的 context 属性赋值给 Form.of 来获得 FormState。或者在表单的构造函数里使用 GlobalKey，然后调用 GlobalKey.currentState 来获得 FormState。

In Flutter, use the Form widget where TextFormField widgets along with the submit button are passed as children. The TextFormField widget has a parameter called onSaved that takes a callback and executes when the form is saved. A FormState object is used to save, reset, or validate each FormField that is a descendant of this Form. To obtain the FormState, you can use Form.of() with a context whose ancestor is the Form, or pass a GlobalKey to the Form constructor and call GlobalKey.currentState().

final formKey = GlobalKey<FormState>();

...

Form(
  key:formKey,
  child: Column(
    children: <Widget>[
      TextFormField(
        validator: (value) => !value.contains('@') ? 'Not a valid email.' : null,
        onSaved: (val) => _email = val,
        decoration: const InputDecoration(
          hintText: 'Enter your email',
          labelText: 'Email',
        ),
      ),
      ElevatedButton(
        onPressed: _submit,
        child: Text('Login'),
      ),
    ],
  ),
)

下面的示例代码展示了 Form.save() 和 formKey （这个实际上是 GlobalKey）如何被用于表单提交的。

The following example shows how Form.save() and formKey (which is a GlobalKey) are used to save the form on submit.

void _submit() {
  final form = formKey.currentState;
  if (form.validate()) {
    form.save();
    showDialog(
      context: context,
      child: AlertDialog(
        title: Text('Alert'),
        content: Text('Email: $_email, password: $_password'),
      )
    );
  }
}

平台相关代码

Platform-specific code

当构建跨平台应用程序的时候，你会尽量多地复用代码。然而，根据不同的应用场景，代码会根据平台的不同有所变化。这就需要提前声明具体的平台来进行独立的实现。

When building a cross-platform app, you want to re-use as much code as possible across platforms. However, scenarios might arise where it makes sense for the code to be different depending on the OS. This requires a separate implementation by declaring a specific platform.

在 React Native 中，下面的实现代码会被用到：

In React Native, the following implementation would be used:

// React Native
if (Platform.OS === 'ios') {
  return 'iOS';
} else if (Platform.OS === 'android') {
  return 'android';
} else {
  return 'not recognised';
}

而在 Flutter 中，则是下面这样的实现：

In Flutter, use the following implementation:

// Flutter
if (Theme.of(context).platform == TargetPlatform.iOS) {
  return 'iOS';
} else if (Theme.of(context).platform == TargetPlatform.android) {
  return 'android';
} else if (Theme.of(context).platform == TargetPlatform.fuchsia) {
  return 'fuchsia';
} else {
  return 'not recognised ';
}

调试

Debugging

应该使用什么工具调试我的 Flutter 应用？

What tools can I use to debug my app in Flutter?

请使用 DevTools 调试你的 Flutter 和 Dart 应用。

Use the DevTools suite for debugging Flutter or Dart apps.

开发者工具包含了 profiling 构建、检查堆栈、检视 widget 树、诊断信息记录、调试、执行代码行观察、调试内存泄漏和内存碎片等。有关更多信息，请参阅 DevTools 文档。

如何进行热重载？

How do I perform a hot reload?

Flutter 的热重载特性可以帮助你快速便捷地实验、构建 UI 和各种特性以及修复 bug。每次修改代码以后，你只需直接热重载你的应用程序即可，而无需重新进行编译。应用程序会根据你的修改进行相应的更新，而程序原有的状态则会被保留。

Flutter’s Stateful Hot Reload feature helps you quickly and easily experiment, build UIs, add features, and fix bugs. Instead of recompiling your app every time you make a change, you can hot reload your app instantly. The app is updated to reflect your change, and the current state of the app is preserved.

在 React Native 中，iOS 模拟器对应的快捷键是 ⌘R，对应 Android 模拟器的快捷键是点击两次 R。

In React Native, the shortcut is ⌘R for the iOS Simulator and tapping R twice on Android emulators.

在 Flutter 中，如果你使用的是 IntelliJ 或者 Android Studio，可以使用 Save All (⌘s/ctrl-s)，或者可以点击工具栏上的 Hot Reload 按钮。如果你是在命令行里使用 flutter run 命令运行的程序，在窗口里输入 r 即可。也可以输入 R 进行彻底的重启。

In Flutter, If you are using IntelliJ IDE or Android Studio, you can select Save All (⌘s/ctrl-s), or you can click the Hot Reload button on the toolbar. If you are running the app at the command line using flutter run, type r in the Terminal window. You can also perform a full restart by typing R in the Terminal window.

How do I access the in-app developer menu?

在 React Native 中，开发者菜单可以通过摇动设备打开：对于 iOS 模拟器的快捷键是 ⌘D 而 Android 模拟器的快捷键是 ⌘M。

In React Native, the developer menu can be accessed by shaking your device: ⌘D for the iOS Simulator or ⌘M for Android emulator.

在 Flutter 中，如果你使用 IDE，那么可以直接使用 IDE 工具。如果你是通过命令行运行 flutter run 来启动应用程序的，你可以在命令行窗口通过输入 h 来打开菜单，或者参考下面的快捷键说明：

In Flutter, if you are using an IDE, you can use the IDE tools. If you start your application using flutter run you can also access the menu by typing h in the terminal window, or type the following shortcuts:

功能 Action	命令行快捷键 Terminal Shortcut	调试功能和属性 Debug functions and properties
应用程序的 widget 层级 Widget hierarchy of the app	`w`	debugDumpApp()
渲染程序的 widget 树 Rendering tree of the app	`t`	debugDumpRenderTree()
层 Layers	`L`	debugDumpLayerTree()
无障碍 Accessibility	`S` (遍历顺序) 或者 `U` (反转点击测试顺序) `S` (traversal order) or `U` (inverse hit test order)	debugDumpSemantics()
打开或者关闭 widget 窗口 To toggle the widget inspector	`i`	WidgetsApp. showWidgetInspectorOverride
显示或者隐藏框架线条 To toggle the display of construction lines	`p`	debugPaintSizeEnabled
模拟不同的操作系统 To simulate different operating systems	`o`	defaultTargetPlatform
叠加显示性能参数 To display the performance overlay	`P`	WidgetsApp. showPerformanceOverlay
将截屏保存为 flutter.png To save a screenshot to flutter. png	`s`
退出 To quit	`q`

动画

Animation

精美的动画效果会使得 UI 更加直观，可以提升整体视觉效果，使应用显得更加精致，从而提升用户体验。 Flutter 的动画框架使得开发者能够更方便地实现简单和复杂的动画。 Flutter SDK 含有很多 Material Design widget。其中已经包括了标准的动画效果，你可以很方便地自定义这些效果。

Well-designed animation makes a UI feel intuitive, contributes to the look and feel of a polished app, and improves the user experience. Flutter’s animation support makes it easy to implement simple and complex animations. The Flutter SDK includes many Material Design widgets that include standard motion effects and you can easily customize these effects to personalize your app.

在 React Native 中，动画 API 用于创建动画。

In React Native, Animated APIs are used to create animations.

在 Flutter 中，使用 Animation 类和 AnimationController 类实现动画。 Animation 是抽象类，内含其当前的值和它的状态（已完成或者已取消）。 AnimationController 类可以正向或者反向播放动画或者停止动画以及为动画设置特定值来自定义动画。

In Flutter, use the Animation class and the AnimationController class. Animation is an abstract class that understands its current value and its state (completed or dismissed). The AnimationController class lets you play an animation forward or in reverse, or stop animation and set the animation to a specific value to customize the motion.

如何添加一个简单的淡入动画效果？

How do I add a simple fade-in animation?

在下面的 React Native 示例中，有一个动画组件，也就是 FadeInView，它是使用 Animated API 创建的。定义了初始的不透明状态，最终状态和动画切换之间的时间间隔。在 Animated 中添加了动画组件，不透明状态 fadeAnim 映射到我们想要添加动画效果的文本组件上，然后在开始动画的时候调用 start()。

In the React Native example below, an animated component, FadeInView is created using the Animated API. The initial opacity state, final state, and the duration over which the transition occurs are defined. The animation component is added inside the Animated component, the opacity state fadeAnim is mapped to the opacity of the Text component that we want to animate, and then, start() is called to start the animation.

// React Native
class FadeInView extends React.Component {
  state = {
    fadeAnim: new Animated.Value(0) // Initial value for opacity: 0
  };
  componentDidMount() {
    Animated.timing(this.state.fadeAnim, {
      toValue: 1,
      duration: 10000
    }).start();
  }
  render() {
    return (
      <Animated.View style={{...this.props.style, opacity: this.state.fadeAnim }} >
        {this.props.children}
      </Animated.View>
    );
  }
}
    ...
<FadeInView>
  <Text> Fading in </Text>
</FadeInView>
    ...

要在 Flutter 中实现相同的动画效果，创建一个 AnimationController 对象，叫它 controller，并且指定时间间隔。在默认配置下， AnimationController 会在给定时间间隔线性的生成从 0.0 到 1.0 的数值。当你的程序可以显示新一帧画面的时候，AnimationController 会生成一个新的值。通常，这个频率在每秒 60 个值。

To create the same animation in Flutter, create an AnimationController object named controller and specify the duration. By default, an AnimationController linearly produces values that range from 0.0 to 1.0, during a given duration. The animation controller generates a new value whenever the device running your app is ready to display a new frame. Typically, this rate is around 60 values per second.

当定义 AnimationController 的时候，你必须传入一个 vsync 对象。 vsync 会防止屏幕显示区域之外的动画消耗不必要的资源。你可以通过添加 TickerProviderStateMixin 到类定义中来使用有状态的对象。 AnimationController 需要传入一个 TickerProvider，它是通过构造函数里的 vsync 参数进行配置的。

When defining an AnimationController, you must pass in a vsync object. The presence of vsync prevents offscreen animations from consuming unnecessary resources. You can use your stateful object as the vsync by adding TickerProviderStateMixin to the class definition. An AnimationController needs a TickerProvider, which is configured using the vsync argument on the constructor.

Tween 定义了起始和结束值之间或者输入段到输出段之间的过渡。如果要在动画中使用 Tween 对象，调用 Tween 对象的 animate 方法，然后把它赋给你要修改的 Animation 对象。

A Tween describes the interpolation between a beginning and ending value or the mapping from an input range to an output range. To use a Tween object with an animation, call the Tween object’s animate() method and pass it the Animation object that you want to modify.

在这个例子中，用到了 FadeTransition widget，它的 opacity 属性映射到了 animation 对象上。

For this example, a FadeTransition widget is used and the opacity property is mapped to the animation object.

要开始动画，使用 controller.forward()。其它的操作也可以使用控制器里的方法，比如 fling() 或者 repeat()。这个例子里，FlutterLogo widget 被用于 FadeTransition widget 中。

To start the animation, use controller.forward(). Other operations can also be performed using the controller such as fling() or repeat(). For this example, the FlutterLogo widget is used inside the FadeTransition widget.

// Flutter
import 'package:flutter/material.dart';

void main() {
  runApp(Center(child: LogoFade()));
}

class LogoFade extends StatefulWidget {
  _LogoFadeState createState() => _LogoFadeState();
}

class _LogoFadeState extends State<LogoFade> with TickerProviderStateMixin {
  Animation animation;
  AnimationController controller;

  initState() {
    super.initState();
    controller = AnimationController(
        duration: const Duration(milliseconds: 3000), vsync: this);
    final CurvedAnimation curve =
    CurvedAnimation(parent: controller, curve: Curves.easeIn);
    animation = Tween(begin: 0.0, end: 1.0).animate(curve);
    controller.forward();
  }

  Widget build(BuildContext context) {
    return FadeTransition(
      opacity: animation,
      child: Container(
        height: 300.0,
        width: 300.0,
        child: FlutterLogo(),
      ),
    );
  }

  dispose() {
    controller.dispose();
    super.dispose();
  }
}

如何为卡片添加滑动动画呢？

How do I add swipe animation to cards?

在 React Native 中，无论 PanResponder 或者第三方库都可被用于滑动动画。

In React Native, either the PanResponder or third-party libraries are used for swipe animation.

在 Flutter 中，要添加滑动动画，使用 Dismissible widget 封装其它子 widget 即可。

In Flutter, to add a swipe animation, use the Dismissible widget and nest the child widgets.

child: Dismissible(
  key: key,
  onDismissed: (DismissDirection dir) {
    cards.removeLast();
  },
  child: Container(
    ...
  ),
),

React Native and Flutter widget equivalent components

下面的表格列举了通用的 React Native 组件与对应的 Flutter widget 和通用的 widget 属性。

The following table lists commonly-used React Native components mapped to the corresponding Flutter widget and common widget properties.

React Native 组件	Flutter Widget	描述
`Button`	`ElevatedButton`	基础的凸起按钮
	onPressed [required]	该回调函数在当按钮被点击的时候被触发。
	Child	按钮的标签
`Button`	`TextButton`	基础的扁平化按钮.
	onPressed [required]	当按钮被点击的时候触发该回调函数。
	Child	按钮的标签
`ScrollView`	`ListView`	一个可滑动的纵向排列的 widget 列表。
	children	( <Widget> [ ]) 要显示的子 widget 列表
	controller	[ `ScrollController` ] 可用于控制滑动 widget 的对象
	itemExtent	[ double ] 如果非空，那么强制所有子 widget 在滑动方向上增加给定的距离
	scroll Direction	[ `Axis` ] 滑动页面的滑动轴
`FlatList`	`ListView.builder`	根据需要创建的一组 widget 的构造函数。
	itemBuilder [required]	[`IndexedWidgetBuilder`] 根据需要创建子 widget。当元素序号大于等于零并且小于队列元素总数时，该回调函数会被调用。
	itemCount	[ int ] 优化了 ListView 对于最大滑动范围的预估能力。
`Image`	`Image`	显示图片的 widget。
	image [required]	要显示的图片
	Image. asset	有多个构造函数可以用于指定图片。
	width, height, color, alignment	图片的风格和布局。
	fit	将图片内嵌到布局对应的空间里。
`Modal`	`ModalRoute`	避免和之前路径交叉的路径。
	animation	路径切换的动画和之前路径向前切换的动画。
`ActivityIndicator`	`LinearProgressIndicator`	一个进度条 widget。
	strokeWidth	圆形线条的宽度。
	backgroundColor	指示进度的背景色。默认是当前主题的 `ThemeData.backgroundColor`。
`ActivityIndicator`	`LinearProgressIndicator`	一个水平条形的进度条。
	value	进度条的进度值。
`RefreshControl`	`RefreshIndicator`	支持 Material 中滑动刷新的 widget
	color	进度指示的前景色。
	onRefresh	当用户拖拽刷新指示器想要刷新的时候会调用该函数。
`View`	`Container`	封装子 widget 的 widget。
`View`	`Column`	将子 widget 纵向排列的 widget。
`View`	`Row`	将子 widget 横向排列的 widget。
`View`	`Center`	将子 widget 放置于中央的 widget。
`View`	`Padding`	将子 widget 按照给定的间隔进行排列的 widget。
	padding [required]	[ EdgeInsets ] 子 widget 间隔。
`TouchableOpacity`	`GestureDetector`	检测手势的 widget。
	onTap	当点击的时候会调用。
	onDoubleTap	当两次点击的时候会调用。
`TextInput`	`TextInput`	调用系统文本输入的接口。
	controller	[ `TextEditingController` ] 用于获取或者修改文本。
`Text`	`Text`	以单一的样式显示文本的文本 widget。
	data	[ String ] 要显示的文本。
	textDirection	[ `TextAlign` ] 文本的方向。
`Switch`	`Switch`	Material Design 样式的开关。
	value [required]	[ boolean ] 开关的开启或者闭合状态。
	onChanged [required]	[ callback ] 当用户点击开关的时候调用。
`Slider`	`Slider`	选择一个范围的值。
	value [required]	[ double ] 当前滑动器的值。
	onChanged [required]	当用户为滑动器选择了新的值时会调用

给 Web 开发者的 Flutter 指南

本文是为那些熟悉用 HTML 与 CSS 语法来管理应用页面中元素的开发者准备的。本文会将 HTML/CSS 代码片段替换为等价的 Flutter/Dart 代码。

This page is for users who are familiar with the HTML and CSS syntax for arranging components of an application’s UI. It maps HTML/CSS code snippets to their Flutter/Dart code equivalents.

One of the fundamental differences between designing a web layout and a Flutter layout, is learning how constraints work, and how widgets are sized and positioned. To learn more, see Understanding constraints.

这些示例包含如下假设：

The examples assume:

HTML 文件以 <!DOCTYPE html> 开头，且为了与 Flutter 模型保持一致，所有 HTML 元素的 CSS 盒模型被设置为 border-box。
The HTML document starts with <!DOCTYPE html>, and the CSS box model for all HTML elements is set to border-box, for consistency with the Flutter model.
```
{
 box-sizing: border-box;
}
```
在 Flutter 中，为了保持语法简洁，”Lorem ipsum” 文本的默认样式由如下 bold24Roboto 变量定义：
In Flutter, the default styling of the “Lorem ipsum” text is defined by the bold24Roboto variable as follows, to keep the syntax simple:
```
TextStyle bold24Roboto = TextStyle(
  color: Colors.white,
  fontSize: 24,
  fontWeight: FontWeight.w900,
);
```

执行基础布局操作

Performing basic layout operations

以下示例将向你展示如何执行最常见的 UI 布局操作。

The following examples show how to perform the most common UI layout tasks.

文本样式与对齐

Styling and aligning text

CSS 所处理的字体样式、大小以及其他文本属性，都是一个 Text widget 子元素 TextStyle 中单独的属性。

Font style, size, and other text attributes that CSS handles with the font and color properties are individual properties of a TextStyle child of a Text widget.

Text widget 中的 textAlign 属性与 CSS 中的 text-align 属性作用相同，用来控制文本的对齐方向。

For text-align property in CSS that is used for aligning text, there is a textAlign property of a Text widget.

在 HTML 和 Flutter 中，子元素或者 widget 都默认锚定在左上方。

In both HTML and Flutter, child elements or widgets are anchored at the top left, by default.

<div class="greybox">
    Lorem ipsum
</div>

.greybox {
      background-color: #e0e0e0; /* grey 300 */
      width: 320px;
      height: 240px;
      font: 900 24px Georgia;
      text-align: center;
    }

var container = Container( // grey box
  child: Text(
    "Lorem ipsum",
    textAlign: TextAlign.center,
    style: TextStyle(
      fontSize: 24,
      fontWeight: FontWeight.w900,
      fontFamily: "Georgia",
    ),
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

设置背景颜色

Setting background color

在 Flutter 中，你可以通过 Container 的 decoration 或者 color 属性来设置背景颜色。但是，你不能同时设置这两个属性，这有可能导致 decoration 覆盖掉 color。当背景是简单的颜色时，应首选 color 属性，对于其他情况，如渐变或图像，推荐使用 decoration 属性。

In Flutter, you set the background color using the color property or the decoration property of a Container. However, you cannot supply both, since it would potentially result in the decoration drawing over the background color. The color property should be preferred when the background is a simple color. For other cases, such as gradients or images, use the decoration property.

CSS 示例使用十六进制颜色，这等价于材质调色板。

The CSS examples use the hex color equivalents to the Material color palette.

<div class="greybox">
  Lorem ipsum
</div>

.greybox {
      background-color: #e0e0e0;  /* grey 300 */
      width: 320px;
      height: 240px;
      font: 900 24px Roboto;
    }

var container = Container( // grey box
  child: Text(
    "Lorem ipsum",
    style: bold24Roboto,
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

var container = Container( // grey box
  child: Text(
    "Lorem ipsum",
    style: bold24Roboto,
  ),
  width: 320,
  height: 240,
  decoration: BoxDecoration(
    color: Colors.grey[300],
  ),
);

居中元素

Centering components

一个 Center widget 可以将它的子元素水平和垂直居中。

A Center widget centers its child both horizontally and vertically.

要用 CSS 实现相似的效果，父元素需要使用一个 flex 或者 table-cell 显示布局。本节示例使用的是 flex 布局。

To accomplish a similar effect in CSS, the parent element uses either a flex or table-cell display behavior. The examples on this page show the flex behavior.

<div class="greybox">
  Lorem ipsum
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center; 
}

var container = Container( // grey box
  child:  Center(
    child:  Text(
      "Lorem ipsum",
      style: bold24Roboto,
    ),
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

设置容器宽度

Setting container width

要指定一个 Container widget 的宽度，请使用它的 width 属性。和 CSS 中的 max-width 属性用于指定容器可调整的宽度最大值不同的是，这里指定的是一个固定宽度。要在 Flutter 中模拟该效果，可以使用 Container 的 constraints 属性。新建一个带有 minWidth 和 maxWidth 属性的 BoxConstraints widget。

To specify the width of a Container widget, use its width property. This is a fixed width, unlike the CSS max-width property that adjusts the container width up to a maximum value. To mimic that effect in Flutter, use the constraints property of the Container. Create a new BoxConstraints widget with a minWidth or maxWidth.

对嵌套的 Container 来说，如果其父元素宽度小于子元素宽度，则子元素会调整尺寸以匹配父元素大小。

For nested Containers, if the parent’s width is less than the child’s width, the child Container sizes itself to match the parent.

<div class="greybox">
  <div class="redbox">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px; 
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
  width: 100%;
  max-width: 240px; 
}

var container = Container( // grey box
  child: Center(
    child: Container( // red box
      child: Text(
        "Lorem ipsum",
        style: bold24Roboto,
      ),
      decoration: BoxDecoration(
        color: Colors.red[400],
      ),
      padding: EdgeInsets.all(16),
      width: 240, //max-width is 240
    ),
  ),
  width: 320, 
  height: 240,
  color: Colors.grey[300],
);

操控位置与大小

Manipulating position and size

以下示例将展示如何对 widget 的位置、大小以及背景进行更复杂的操作。

The following examples show how to perform more complex operations on widget position, size, and background.

设置绝对位置

Setting absolute position

默认情况下， widget 相对于其父元素定位。

By default, widgets are positioned relative to their parent.

要通过 x-y 坐标指定一个 widget 的绝对位置，把它嵌套在一个 Positioned widget 中，而该 widget 则需被嵌套在一个 Stack widget 中。

To specify an absolute position for a widget as x-y coordinates, nest it in a Positioned widget that is, in turn, nested in a Stack widget.

<div class="greybox">
  <div class="redbox">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  position: relative; 
}
.redbox {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
  position: absolute;
  top: 24px;
  left: 24px; 
}

var container = Container( // grey box
  child: Stack(
    children: [
      Positioned( // red box
        child:  Container(
          child: Text(
            "Lorem ipsum",
            style: bold24Roboto,
          ),
          decoration: BoxDecoration(
            color: Colors.red[400],
          ),
          padding: EdgeInsets.all(16),
        ),
        left: 24,
        top: 24,
      ),
    ],
  ), 
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

旋转元素

Rotating components

要旋转一个 widget，请将它嵌套在 Transform widget 中。使用 Transform widget 的 alignment 和 origin 属性分别来指定转换原点（支点）的相对和绝对位置信息。

To rotate a widget, nest it in a Transform widget. Use the Transform widget’s alignment and origin properties to specify the transform origin (fulcrum) in relative and absolute terms, respectively.

对于简单的 2D 旋转，widget 是依据弧度在 Z 轴上旋转的，创建一个新的 Matrix4 标志对象，并使用它的 rotateZ() 方法使用弧度系数 (角度 × π / 180) 以指定旋转系数。

For a simple 2D rotation, in which the widget is rotated on the Z axis, create a new Matrix4 identity object and use its rotateZ() method to specify the rotation factor using radians (degrees × π / 180).

<div class="greybox">
  <div class="redbox">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
  transform: rotate(15deg); 
}

var container = Container( // gray box
  child: Center(
    child:  Transform(
      child:  Container( // red box
        child: Text(
          "Lorem ipsum",
          style: bold24Roboto,
          textAlign: TextAlign.center,
        ),
        decoration: BoxDecoration(
          color: Colors.red[400],
        ),
        padding: EdgeInsets.all(16),
      ),
      alignment: Alignment.center,
      transform: Matrix4.identity()
        ..rotateZ(15 * 3.1415927 / 180),
    ), 
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

缩放元素

Scaling components

要缩放或放大一个 widget，请将它嵌套在一个 Transform widget 中。使用 Transform widget 的 alignment 和 origin 属性分别来指定缩放原点（支点）的相对和绝对信息。

To scale a widget up or down, nest it in a Transform widget. Use the Transform widget’s alignment and origin properties to specify the transform origin (fulcrum) in relative or absolute terms, respectively.

对于沿 x 轴的简单缩放操作，新建一个 Matrix4 标识对象并用它的 scale() 方法来指定缩放因系数。

For a simple scaling operation along the x-axis, create a new Matrix4 identity object and use its scale() method to specify the scaling factor.

当你缩放一个父 widget 时，它的子 widget 也会相应被缩放。

When you scale a parent widget, its child widgets are scaled accordingly.

<div class="greybox">
  <div class="redbox">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
  transform: scale(1.5); 
}

var container = Container( // gray box
  child: Center(
    child:  Transform(
      child:  Container( // red box
        child: Text(
          "Lorem ipsum",
          style: bold24Roboto,
          textAlign: TextAlign.center,
        ),
        decoration: BoxDecoration(
          color: Colors.red[400],
        ),
        padding: EdgeInsets.all(16),
      ),
      alignment: Alignment.center,
      transform: Matrix4.identity()
        ..scale(1.5),
     ), 
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

应用线性变换

Applying a linear gradient

要将线性变换应用在 widget 的背景上，请将它嵌套在一个 Container widget 中。然后用 Container widget 的 decoration 属性生成一个 BoxDecoration 对象，然后使用 BoxDecoration 的 gradient 属性来变换背景填充内容。

To apply a linear gradient to a widget’s background, nest it in a Container widget. Then use the Container widget’s decoration property to create a BoxDecoration object, and use BoxDecoration’s gradient property to transform the background fill.

变换“角度”基于 Alignment (x, y) 取值来定：

The gradient “angle” is based on the Alignment (x, y) values:

If the beginning and ending x values are equal, the gradient is vertical (0° | 180°).

如果开始和结束的 x 值相同，变换将是垂直的（0° 180°）。
If the beginning and ending y values are equal, the gradient is horizontal (90° | 270°).

如果开始和结束的 y 值相同，变换将是水平的（90° 270°）。

垂直变换

Vertical gradient

<div class="greybox">
  <div class="redbox">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  padding: 16px;
  color: #ffffff;
  background: linear-gradient(180deg, #ef5350, rgba(0, 0, 0, 0) 80%); 
}

var container = Container( // grey box
  child: Center(
    child: Container( // red box
      child: Text(
        "Lorem ipsum",
        style: bold24Roboto,
      ),
      decoration: BoxDecoration(
        gradient: LinearGradient(
          begin: const Alignment(0.0, -1.0),
          end: const Alignment(0.0, 0.6),
          colors: <Color>[
            const Color(0xffef5350),
            const Color(0x00ef5350)
          ],
        ),
      ), 
      padding: EdgeInsets.all(16),
    ),
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

水平变换

Horizontal gradient

<div class="greybox">
  <div class="redbox">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  padding: 16px;
  color: #ffffff;
  background: linear-gradient(90deg, #ef5350, rgba(0, 0, 0, 0) 80%); 
}

var container = Container( // grey box
  child: Center(
    child: Container( // red box
      child: Text(
        "Lorem ipsum",
        style: bold24Roboto,
      ),
      decoration: BoxDecoration(
        gradient: LinearGradient(
          begin: const Alignment(-1.0, 0.0),
          end: const Alignment(0.6, 0.0),
          colors: <Color>[
            const Color(0xffef5350),
            const Color(0x00ef5350)
          ],
        ),
      ), 
      padding: EdgeInsets.all(16),
    ),
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

操控图形

Manipulating shapes

以下示例将展示如何新建和自定义图形。

The following examples show how to make and customize shapes.

圆角

Rounding corners

在矩形上实现圆角，请用 BoxDecoration 对象的 borderRadius 属性。新建一个 BorderRadius 对象来指定每个圆角的半径大小。

To round the corners of a rectangular shape, use the borderRadius property of a BoxDecoration object. Create a new BorderRadius object that specifies the radius for rounding each corner.

<div class="greybox">
  <div class="redbox">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* gray 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
  border-radius: 8px; 
}

var container = Container( // grey box
  child: Center(
    child: Container( // red circle
      child: Text(
        "Lorem ipsum",
        style: bold24Roboto,
      ),
      decoration: BoxDecoration(
        color: Colors.red[400],
        borderRadius: BorderRadius.all(
          const Radius.circular(8),
        ), 
      ),
      padding: EdgeInsets.all(16),
    ),
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

添加盒阴影 (box shadows)

Adding box shadows

在 CSS 中你可以通过 box-shadow 属性快速指定阴影偏移与模糊范围。本例展示了两个盒阴影的属性设置：

In CSS you can specify shadow offset and blur in shorthand, using the box-shadow property. This example shows two box shadows, with properties:

xOffset: 0px, yOffset: 2px, blur: 4px, color: black @80% alpha
xOffset: 0px, yOffset: 06x, blur: 20px, color: black @50% alpha

在 Flutter 中，每个属性与其取值都是单独指定的。请使用 BoxDecoration 的 boxShadow 属性来生成一系列 BoxShadow widget。你可以定义一个或多个 BoxShadow widget，这些 widget 共同用于设置阴影深度、颜色等等。

In Flutter, each property and value is specified separately. Use the boxShadow property of BoxDecoration to create a list of BoxShadow widgets. You can define one or multiple BoxShadow widgets, which can be stacked to customize the shadow depth, color, and so on.

<div class="greybox">
  <div class="redbox">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.8),
              0 6px 20px rgba(0, 0, 0, 0.5);
}

var container = Container( // grey box
  child: Center(
    child: Container( // red box
      child: Text(
        "Lorem ipsum",
        style: bold24Roboto,
      ),
      decoration: BoxDecoration(
        color: Colors.red[400],
        boxShadow: [
          BoxShadow (
            color: const Color(0xcc000000),
            offset: Offset(0, 2),
            blurRadius: 4,
          ),
          BoxShadow (
            color: const Color(0x80000000),
            offset: Offset(0, 6),
            blurRadius: 20,
          ),
        ], 
      ),
      padding: EdgeInsets.all(16),
    ),
  ),
  width: 320,
  height: 240,
  decoration: BoxDecoration(
    color: Colors.grey[300],
  ),
  margin: EdgeInsets.only(bottom: 16),
);

生成圆与椭圆

Making circles and ellipses

尽管 CSS 中有基础图形，用 CSS 生成圆可以用一个变通方案，即将矩形的四边 border-radius 均设成50%。

Making a circle in CSS requires a workaround of applying a border-radius of 50% to all four sides of a rectangle, though there are basic shapes.

虽然 BoxDecoration 的 borderRadius 属性支持这样设置，Flutter 为 BoxShape enum 提供一个 shape 属性用于实现同样的目的。

While this approach is supported with the borderRadius property of BoxDecoration, Flutter provides a shape property with BoxShape enum for this purpose.

<div class="greybox">
  <div class="redcircle">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* gray 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redcircle {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
  text-align: center;
  width: 160px;
  height: 160px;
  border-radius: 50%; 
}

var container = Container( // grey box
  child: Center(
    child: Container( // red circle
      child: Text(
        "Lorem ipsum",
        style: bold24Roboto,
        textAlign: TextAlign.center, 
      ),
      decoration: BoxDecoration(
        color: Colors.red[400],
        shape: BoxShape.circle, 
      ),
      padding: EdgeInsets.all(16),
      width: 160,
      height: 160, 
    ),
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

操控文本

Manipulating text

以下示例展示了如何设置字体和其他文本属性。他们同时还展示了如何变换文本字符、自定义间距以及生成摘要。

The following examples show how to specify fonts and other text attributes. They also show how to transform text strings, customize spacing, and create excerpts.

文字间距调整

Adjusting text spacing

在 CSS 中你可以通过分别给 letter-spacing 和 word-spacing 属性的长度赋值来指定每个字母��及每个单词间的空白距离。距离的单位可以是 px, pt, cm, em 等等。

In CSS you specify the amount of white space between each letter or word by giving a length value for the letter-spacing and word-spacing properties, respectively. The amount of space can be in px, pt, cm, em, etc.

在 Flutter 中，你可以在 Text widget 子元素 TextStyle 的 letterSpacing 与 wordSpacing 属性中将间距设置为逻辑像素（允许负值）。

In Flutter, you specify white space as logical pixels (negative values are allowed) for the letterSpacing and wordSpacing properties of a TextStyle child of a Text widget.

<div class="greybox">
  <div class="redbox">
    Lorem ipsum
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
  letter-spacing: 4px; 
}

var container = Container( // grey box
  child: Center(
    child: Container( // red box
      child: Text(
        "Lorem ipsum",
        style: TextStyle(
          color: Colors.white,
          fontSize: 24,
          fontWeight: FontWeight.w900,
          letterSpacing: 4, 
        ),
      ),
      decoration: BoxDecoration(
        color: Colors.red[400],
      ),
      padding: EdgeInsets.all(16),
    ),
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

内联样式更改

Making inline formatting changes

一个 Text widget 允许你展示同一类样式的文本。为了展现具有多种样式（本例中，是一个带重音的单词）的文本，需要改用 RichText widget。它的 text 属性可以指定一个或多个可以单独设置样式的 TextSpan widget。

A Text widget lets you display text with some formatting characteristics. To display text that uses multiple styles (in this example, a single word with emphasis), use a RichText widget instead. Its text property can specify one or more TextSpan widgets that can be individually styled.

在接下来的示例中，”Lorem” 位于 TextSpan widget 中，具有默认（继承）文本样式，”ipsum” 位于具有自定义样式、单独的一个 TextSpan 中。

In the following example, “Lorem” is in a TextSpan widget with the default (inherited) text styling, and “ipsum” is in a separate TextSpan with custom styling.

<div class="greybox">
  <div class="redbox">
    Lorem <em>ipsum</em>
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
}
 .redbox em {
  font: 300 48px Roboto;
  font-style: italic;
}

var container = Container( // grey box
  child: Center(
    child: Container( // red box
      child:  RichText(
        text: TextSpan(
          style: bold24Roboto,
          children: <TextSpan>[
            TextSpan(text: "Lorem "),
            TextSpan(
              text: "ipsum",
              style: TextStyle(
                fontWeight: FontWeight.w300,
                fontStyle: FontStyle.italic,
                fontSize: 48,
              ),
            ),
          ],
        ),
      ), 
      decoration: BoxDecoration(
        color: Colors.red[400],
      ),
      padding: EdgeInsets.all(16),
    ),
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

生成文本摘要

Creating text excerpts

一个摘要会展示一个段落中文本的初始行内容，并常用省略号处理溢出的文本内容。在 HTML/CSS 中，摘录不能超过一行。在多行之后进行截断需要运行一些 JavaScript 代码。

An excerpt displays the initial line(s) of text in a paragraph, and handles the overflow text, often using an ellipsis. In HTML/CSS an excerpt can be no longer than one line. Truncating after multiple lines requires some JavaScript code.

在 Flutter 中，使用 Text widget 的 maxLines 属性来指定包含在摘要中的行数，以及 overflow 属性来处理溢出文本。

In Flutter, use the maxLines property of a Text widget to specify the number of lines to include in the excerpt, and the overflow property for handling overflow text.

<div class="greybox">
  <div class="redbox">
    Lorem ipsum dolor sit amet, consec etur
  </div>
</div>

.greybox {
  background-color: #e0e0e0; /* grey 300 */
  width: 320px;
  height: 240px;
  font: 900 24px Roboto;
  display: flex;
  align-items: center;
  justify-content: center;
}
.redbox {
  background-color: #ef5350; /* red 400 */
  padding: 16px;
  color: #ffffff;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap; 
}

var container = Container( // grey box
  child: Center(
    child: Container( // red box
      child: Text(
        "Lorem ipsum dolor sit amet, consec etur",
        style: bold24Roboto,
        overflow: TextOverflow.ellipsis,
        maxLines: 1, 
      ),
      decoration: BoxDecoration(
        color: Colors.red[400],
      ),
      padding: EdgeInsets.all(16),
    ),
  ),
  width: 320,
  height: 240,
  color: Colors.grey[300],
);

给 Xamarin.Forms 开发者的 Flutter 指南

项目设置
Project setup
- app 是如何运行的？
  How does the app start?
- 如何创建一个页面？
  How do you create a page?
视图
Views
导航
Navigation
- 如何在页面之间导航？
  How do I navigate between pages?
- 如何导航到其它应用程序？
  How do I navigate to another app?
异步 UI
Async UI
项目结构与资源
Project structure & resources
应用程序生命周期
Application lifecycle
- 如何侦听应用程序的生命周期事件？
  How do I listen to application lifecycle events?
布局
Layouts
手势检测和触摸事件处理
Gesture detection and touch event handling
- 如何在Flutter中向 widget 添加手势识别器?
  How do I add GestureRecognizers to a widget in Flutter?
- 我如何处理 widget 上的其他手势？
  How do I handle other gestures on widgets?
列表视图和适配器
Listviews and adapters
文本处理
Working with text
- 如何在文本（Text） widget 上设置自定义字体?
  How do I set custom fonts on my text widgets?
- 如何设置文本 widget 的样式？
  How do I style my text widgets?
表单录入
Form input
Flutter 插件
Flutter plugins
与硬件、第三方服务和平台交互
Interacting with hardware, third party services, and the platform
主题（样式）
Themes (Styles)
- 如何美化我的应用程序？
  How do I theme my app?
数据库与本地存储
Databases and local storage
- 如何访问共享首选项或用户默认值?
  How do I access shared preferences or UserDefaults?
- 在 Flutter 中如何访问 SQLite
  How do I access SQLite in Flutter?
调试
Debugging
- 应该使用什么工具调试我的 Flutter 应用？
  What tools can I use to debug my app in Flutter?
通知
Notifications
- 如何设置通知推送?
  How do I set up push notifications?

本文档旨在帮助 Xamarin.Forms 开发者利用已有的知识去构建 Flutter 移动应用。如果你懂得 Xamarin.Forms 框架的基本原理，那么你就可以将本文档当作你开始 Flutter 开发的不错的起点。

This document is meant for Xamarin.Forms developers looking to apply their existing knowledge to build mobile apps with Flutter. If you understand the fundamentals of the Xamarin.Forms framework, then you can use this document as a jump start to Flutter development.

你的 Android 和 iOS 知识以及技能组合在构建 Flutter 时都是有价值的，因为 Flutter 依赖的原生系统配置都与你配置 Xamarin.Forms 原生项目时一样。 Flutter 框架与你创建一个单独的界面时也是一样的，这在多个平台中同样适用。

Your Android and iOS knowledge and skill set are valuable when building with Flutter, because Flutter relies on the native operating system configurations, similar to how you would configure your native Xamarin.Forms projects. The Flutter Frameworks is also similar to how you create a single UI, that is used on multiple platforms.

本文档可用做可指导手册来翻查与你需求最为相关的问题。

This document can be used as a cookbook by that are most relevant to your needs.

项目设置

Project setup

app 是如何运行的？

How does the app start?

对于 Xamarin.Forms 里的每个平台，你可以调用 LoadApplication 方法，创建一个新应用并运行你的 app 。

For each platform in Xamarin.Forms, which creates a new application and starts your app.

LoadApplication(new App());

在 Flutter 中，加载 Flutter app 的默认主入口点是 main。

In Flutter, the default main entry point is main where you load your Flutter app.

void main() {
  runApp(MyApp());
}

在 Xamarin.Forms 中，你分配一个 Page 到 Application 类中的 MainPage 属性。

In Xamarin.Forms, you assign a Page to the MainPage property in the Application class.

public class App : Application
{
    public App()
    {
        MainPage = new ContentPage
        {
            Content = new Label
            {
                Text = "Hello World",
                HorizontalOptions = LayoutOptions.Center,
                VerticalOptions = LayoutOptions.Center
            }
        };
    }
}

在 Flutter 中，“万物皆 widget”，甚至连应用本身也是。接下来的示例展示了 MyApp ,一个简单的应用 Widget。

In Flutter, “everything is a widget”, even the application itself. The following example shows MyApp, a simple application Widget.

class MyApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return Center(
        child: Text("Hello World!", textDirection: TextDirection.ltr));
  }
}

如何创建一个页面？

How do you create a page?

Xamarin.Forms 拥有一些不同类型的页面； ContentPage 是最为通用的。在 Flutter 中，指定一个应用程序 widget 来控制你的根页面。你可以使用一个 MaterialApp widget，它支持 Material Design，或者你也可以使用 CupertinoApp widget，它能用来创建 ios 风格的应用，或者你也可以使用等级较低的 WidgetsApp，可供你随心所欲地定制。

Xamarin.Forms has many different types of pages; ContentPage is the most common. In Flutter, you specify an application widget that holds your root page. You can use a MaterialApp widget, which supports Material Design, or you can use a CupertinoApp widget, which supports an iOS-style app, or you can use the lower level WidgetsApp, which you can customize in any way you want.

接下来的代码定义了一个主页，一个有状态的 widget。在 Flutter 中，除了以下两个类型的 widget 外，其它 widget 都是不可变的：有状态和无状态 widget。无状态 widget 的示例都是标题、图标或图片。

The following code defines the home page, a stateful widget. In Flutter, all widgets are immutable, but two types of widgets are supported: stateful and stateless. Examples of a stateless widget are titles, icons, or images.

下面的示例使用 MaterialApp，它在 home 属性中控制它的根页面。

The following example uses MaterialApp, which holds its root page in the home property.

class MyApp extends StatelessWidget {
  // This widget is the root of your application(这个 widget 是你的应用程序的根 widget)。

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

从这里开始，真正的首页是另一个你在里面创建了状态的 widget。

From here, your actual first page is another Widget, in which you create your state.

一个有状态 widget，例如下面的 MyHomePage，包含两个部分。第一部分，是它自身不变的，创建一个状态对象（State object）来管控对象的状态。状态对象持续存在于 widget 的整个生命周期中。

A stateful widget, such as MyHomePage below, consists of two parts. The first part, which is itself immutable, creates a State object that holds the state of the object. The State object persists over the life of the widget.

class MyHomePage extends StatefulWidget {
  MyHomePage({Key key, this.title}) : super(key: key);

  final String title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

状态对象实现了有状态 widget 中的构建方法。

The State object implements the build() method for the stateful widget.

当 widget 树的状态发生了改变，将会调用 setState() 触发 widget 当中该部分UI的构建。确保只在需要时调用 setState() ，并且在只有部分 widget 树发生变化时调用，否则会造成糟糕的UI性能表现。

When the state of the widget tree changes, call setState(), which triggers a build of that portion of the UI. Make sure to call setState() only when necessary, and only on the part of the widget tree that has changed, or it can result in poor UI performance.

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        // Take the value from the MyHomePage object that was created by
        // the App.build method, and use it to set the appbar title.
        title: Text(widget.title),
      ),
      body: Center(
        // Center is a layout widget. It takes a single child and positions it
        // in the middle of the parent.
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline4,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: Icon(Icons.add),
      ),
    );
  }
}

在 Flutter 中的UI（也就是这里所说的 widget 树）是不可变的，意思是说它一旦被构建，你就无法再改变他的状态。当你修改状态 类中的字段，就要再次调用 setState 来重新构建整个 widget 树。

In Flutter, the UI (also known as widget tree), is immutable, meaning you can’t change its state once it’s built. You change fields in your State class, then call setState() to rebuild the entire widget tree again.

这个生成UI的方式不同于 Xamarin.Forms，但是这种方法却有很多益处。

This way of generating UI is different than Xamarin.Forms, but there are many benefits to this approach.

视图

Views

在 Flutter 中页面（Page）与元素（Element）的相同的是什么？

What is the equivalent of a Page or Element in Flutter?

一个 ContentPage、TabbedPage、FlyoutPage 就是你可以在 Xamarin.Forms 应用程序中使用的全部页面类型。这些页面会控制元素（Element）来显示各种控件。在 Xamarin.Forms 中，Entry 或者 Button 就是一个 元素 的示例。

ContentPage, TabbedPage, FlyoutPage are all types of pages you might in a Xamarin.Forms application. These pages would then hold Elements to display the various controls. In Xamarin.Forms an Entry or Button are examples of an Element.

在 Flutter 中，几乎所有东西都是 widget，一个页面在 Flutter 中被称作路由（Route），也是一个 widget。按钮、进度条、动画控制器都是 widget。当构建一个路由时，就会创建一棵 widget 树。

In Flutter, almost everything is a widget. A Page, called a Route in Flutter, is a widget. Buttons, progress bars, and animation controllers are all widgets. When building a route, you create a widget tree.

Flutter 包含 Material 组件库。这些都是实现了 Material Design 指南的 widget。 Material Design 是一个灵活的针对所有平台的设计系统，包括 iOS。

不过，Flutter 有足够灵活和自描述性 (expressive) 去实现任何设计语言。举个例子，在 iOS 上，你可以用 Cupertino widgets 来生成一个看起来像苹果 iOS 设计语言的接口。

如何更新 widget？

How do I update widgets?

在 Xamarin.Forms 中，每一个页面或者元素都是一个有状态的类，拥有一些属性和方法。通过更新一个属性来更新你的元素，而且这会传递到原生控件。

In Xamarin.Forms, each Page or Element is a stateful class, that has properties and methods. You update your Element by updating a property, and this is propagated down to the native control.

在 Flutter 中，widget是不可变的，你不可以直接地通过修改一个属性来更新它们，而是应该使用 widget 的状态。

In Flutter, Widgets are immutable and you can’t directly update them by changing a property, instead you have to work with the widget’s state.

有状态 widget 和无状态 widget 的概念就是出自这里， 无状态 widget（StatelessWidget）顾名思义，就是一个没有状态信息的 widget。

This is where the concept of Stateful vs Stateless widgets comes from. A StatelessWidget is just what it sounds like—a widget with no state information.

当你在描绘用户界面的一个不依赖除对象中的配置信息之外任何东西的部分时， StatelessWidgets 是有用的。

StatelessWidgets are useful when the part of the user interface you are describing does not depend on anything other than the configuration information in the object.

举个例子，在 Xamarin.Forms 中，可以轻而易举地用你的logo替换一张图片。这个logo将不会在运行过程中修改，所以在 Flutter 会使用StatelessWidget。

For example, in Xamarin.Forms, this is similar to placing an Image with your logo. The logo is not going to change during runtime, so use a StatelessWidget in Flutter.

如果你想动态地基于进行了 HTTP 调用或者用户交互后接收到的数据来修改 UI，你需要使用 StatefulWidget 并告诉 Flutter 框架这个 widget 的 状态（State） 已经被更新了所以它可以更新那个 widget。

这里要记下的重要内容是有状态和无状态 widget 的核心行为都是一样的。他们重建每个结构，不同的是StatefulWidget拥有一个状态（State） 对象来跨结构储存状态数据和恢复它。

如果你有疑惑，那么就记住这个规则：如果一个 widget 改变了（例如是因为用户交互），它就是有状态的。相反，如果一个 widget 对修改作出反应，包含它的父 widget 如果本身没有对修改作出反应，仍然可以是无状态的。

接下来的示例展示了如何使用一个StatelessWidget。一个公共的 StatelessWidget是Text widget。如果你查阅 Text widget 的实现，你会发现他是 StatelessWidget 的子类。

Text(
  'I like Flutter!',
  style: TextStyle(fontWeight: FontWeight.bold),
);

如你所见，文本 widget 没有状态信息与它关联，它只渲染在它的构造函数中呈现的内容，没有更多。

As you can see, the Text widget has no state information associated with it, it renders what is passed in its constructors and nothing more.

但是，如果你想动态地作出 “I Like Flutter”的修改呢？例如在点击一个FloatingActionButton时。

But, what if you want to make “I Like Flutter” change dynamically, for example when clicking a FloatingActionButton?

为了实现这个目标，需要将 Text widget 封装到一个StatefulWidget中，并在用用户点击按钮时更新它，正如接下来的例子：

To achieve this, wrap the Text widget in a StatefulWidget and update it when the user clicks the button, as shown in the following example:

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  // Default placeholder text
  String textToShow = "I Like Flutter";

  void _updateText() {
    setState(() {
      // Update the text
      textToShow = "Flutter is Awesome!";
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: Center(child: Text(textToShow)),
      floatingActionButton: FloatingActionButton(
        onPressed: _updateText,
        tooltip: 'Update Text',
        child: Icon(Icons.update),
      ),
    );
  }
}

该如何布局我的 widget 呢？什么东西可以等价于一个 XAML 文件？

How do I lay out my widgets? What is the equivalent of an XAML file?

在 Xamarin.Forms 中，大部分开发者用 XAML 写布局，尽管有时用 C#。在 Flutter 中编码一棵 widget 树来编写布局。

In Xamarin.Forms, most developers write layouts in XAML, though sometimes in C#. In Flutter, you write your layouts with a widget tree in code.

接下来的示例展示如何显示一个简单的带填充（padding）的 widget：

The following example shows how to display a simple widget with padding:

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(
      title: Text("Sample App"),
    ),
    body: Center(
      child: ElevatedButton(
        style: ElevatedButton.styleFrom(
          padding: EdgeInsets.only(left: 20.0, right: 30.0),
        ),
        onPressed: () {},
        child: Text('Hello'),
      ),
    ),
  );
}

您可以查看 Flutter 在 widget 目录中提供的布局。

You can view the layouts that Flutter has to offer in the widget catalog.

如何从布局中添加或移除一个元素?

How do I add or remove an Element from my layout?

在 Xamarin.Forms 中，你需要在代码中移除或添加一个 元素（Element）。如果它说一个列表，这将会涉及设置 Content 属性或者调用 Add() 或者 Remove() 方法。

In Xamarin.Forms, you had to remove or add an Element in code. This involved either setting the Content property or calling Add() or Remove() if it was a list.

在 Flutter 中，因为 widget 都是不可变的，所以没有直接对等的东西。相反，你可以将一个返回一个 widget 的函数传递给父级，并用布尔标控制它的子 widget 的创建。

In Flutter, because widgets are immutable there is no direct equivalent. Instead, you can pass a function to the parent that returns a widget, and control that child’s creation with a boolean flag.

下面的示例展示当用户点击 FloatingActionButton 时，如何在两个 widget 之间切换。

The following example shows how to toggle between two widgets when the user clicks the FloatingActionButton:

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  // Default value for toggle
  bool toggle = true;
  void _toggle() {
    setState(() {
      toggle = !toggle;
    });
  }

  _getToggleChild() {
    if (toggle) {
      return Text('Toggle One');
    } else {
      return CupertinoButton(
        onPressed: () {},
        child: Text('Toggle Two'),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: Center(
        child: _getToggleChild(),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _toggle,
        tooltip: 'Update Text',
        child: Icon(Icons.update),
      ),
    );
  }
}

How do I animate a widget?

在 Xamarin.Forms 中，你可以利用包括例如 FadeTo 和 TranslateTo 等方法的视图扩展（ViewExtensions）来创建简单的动画。你会在一个视图中使用这些方法来执行需要的动画。

In Xamarin.Forms, you create simple animations using ViewExtensions that include methods such as FadeTo and TranslateTo. You would use these methods on a view to perform the required animations.

<Image Source="{Binding MyImage}" x:Name="myImage" />

然后再后面的代码或一个动作中，这个会在1秒内淡入这张图像。

Then in code behind, or a behavior, this would fade in the image, over a 1 second period.

myImage.FadeTo(0, 1000);

在 Flutter 中，通过封装 widget 到一个动画 widget 中，可以使用动画类库来让 widget 动起来。使用一个 AnimationController ，即一个可以暂停、寻找、停止和倒退动画的 Animation<double> 。它需要一个滴答器（Ticker），当垂直同步（vsync）发生时，会发出信号，并在运行时的每一帧都会产生0和1之间的线性插值。然后你可以创建一个或多个动画并把它们附加到控制器上。

In Flutter, you animate widgets using the animation library by wrapping widgets inside an animated widget. Use an AnimationController, which is an Animation<double> that can pause, seek, stop and reverse the animation. It requires a Ticker that signals when vsync happens, and produces a linear interpolation between 0 and 1 on each frame while it’s running. You then create one or more Animations and attach them to the controller.

举个例子，你可以使用 CurvedAnimation 来实现一个沿着插值曲线的动画。在这个场景中，控制器说一个动画进展的“大师”源，而 CurvedAnimation 计算用来替代控制器默认线性运动的曲线。跟 widget 一样，Flutter 中的动画与组成一起工作。

当你在构建一个 widget 树，赋值一个 动画（Animation） 给一个 widget 的一个动画属性时，比如 渐退（FadeTransition） 的不透明度，会告诉控制器开始执行动画。

When building the widget tree, you assign the Animation to an animated property of a widget, such as the opacity of a FadeTransition, and tell the controller to start the animation.

下面的实例展示如何去写一个 渐退（FadeTransition），当你按下 FloatingActionButton 时，它会把 widget 渐变到一个logo。

The following example shows how to write a FadeTransition that fades the widget into a logo when you press the FloatingActionButton:

import 'package:flutter/material.dart';

void main() {
  runApp(FadeAppTest());
}

class FadeAppTest extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Fade Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyFadeTest(title: 'Fade Demo'),
    );
  }
}

class MyFadeTest extends StatefulWidget {
  MyFadeTest({Key key, this.title}) : super(key: key);
  final String title;
  @override
  _MyFadeTest createState() => _MyFadeTest();
}

class _MyFadeTest extends State<MyFadeTest> with TickerProviderStateMixin {
  AnimationController controller;
  CurvedAnimation curve;

  @override
  void initState() {
    super.initState();
    controller = AnimationController(duration: const Duration(milliseconds: 2000), vsync: this);
    curve = CurvedAnimation(parent: controller, curve: Curves.easeIn);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
          child: Container(
              child: FadeTransition(
                  opacity: curve,
                  child: FlutterLogo(
                    size: 100.0,
                  )))),
      floatingActionButton: FloatingActionButton(
        tooltip: 'Fade',
        child: Icon(Icons.brush),
        onPressed: () {
          controller.forward();
        },
      ),
    );
  }
}

更多信息，可以查阅动画 & 运动 widget，动画教程，以及动画概述。

For more information, see Animation & Motion widgets, the Animations tutorial, and the Animations overview.

如何在屏幕上绘图？

How do I draw/paint on the screen?

Xamarin.Forms 从来没有任何内置的方法来直接在屏幕上绘图。如果他们需要一个自定义图像绘制，大多数使用 SkiaSharp。在 Flutter中，你可以直接访问 Skia 画布（Skia Canvas）方便地在屏幕上绘图。

Xamarin.Forms never had a built in way to draw directly on the screen. Many would use SkiaSharp, if they needed a custom image drawn. In Flutter, you have direct access to the Skia Canvas and can easily draw on screen.

Flutter 拥有两个类来帮助你在画布上绘图：CustomPaint 和 CustomPainter，后者实现了你在画布上绘图的算法。

Flutter has two classes that help you draw to the canvas: CustomPaint and CustomPainter, the latter of which implements your algorithm to draw to the canvas.

如果想学习如何在 Flutter 中实现一个签名画手，请阅读 Collin 在 StackOverflow 的回答。

To learn how to implement a signature painter in Flutter, see Collin’s answer on StackOverflow.

import 'package:flutter/material.dart';

void main() => runApp(MaterialApp(home: DemoApp()));

class DemoApp extends StatelessWidget {
  Widget build(BuildContext context) => Scaffold(body: Signature());
}

class Signature extends StatefulWidget {
  SignatureState createState() => SignatureState();
}

class SignatureState extends State<Signature> {
  List<Offset> _points = <Offset>[];
  Widget build(BuildContext context) {
    return GestureDetector(
      onPanUpdate: (DragUpdateDetails details) {
        setState(() {
          RenderBox referenceBox = context.findRenderObject();
          Offset localPosition =
          referenceBox.globalToLocal(details.globalPosition);
          _points = List.from(_points)..add(localPosition);
        });
      },
      onPanEnd: (DragEndDetails details) => _points.add(null),
      child: CustomPaint(painter: SignaturePainter(_points), size: Size.infinite),
    );
  }
}

class SignaturePainter extends CustomPainter {
  SignaturePainter(this.points);
  final List<Offset> points;
  void paint(Canvas canvas, Size size) {
    var paint = Paint()
      ..color = Colors.black
      ..strokeCap = StrokeCap.round
      ..strokeWidth = 5.0;
    for (int i = 0; i < points.length - 1; i++) {
      if (points[i] != null && points[i + 1] != null)
        canvas.drawLine(points[i], points[i + 1], paint);
    }
  }
  bool shouldRepaint(SignaturePainter other) => other.points != points;
}

widget 的不透明度在哪里？

Where is the widget’s opacity?

Xamarin.Forms 上，所有 虚拟元素（VisualElement）都拥有一个不透明度。在 Flutter 中，你需要封装一个 widget 到一个不透明度 widget 来实现它。

On Xamarin.Forms, all VisualElements have an Opacity. In Flutter, you need to wrap a widget in an Opacity widget to accomplish this.

如何构建一个自定义 widget ？

How do I build custom widgets?

在 Xamarin.Forms 中，通常派生 VisualElement 或使用一个已有的 VisualElement ，来重写和实现所需行为的方法。

In Xamarin.Forms, you typically subclass VisualElement, or use a pre-existing VisualElement, to override and implement methods that achieve the desired behavior.

在 Flutter 中，通过组合（composing）更小的 widget（而不是扩展它们）来构建一个自定义 widget。这有点类似于基于 Grid 实现自定义控件，其中添加了大量 VisualElement，同时使用自定义逻辑进行扩展。

In Flutter, build a custom widget by composing smaller widgets (instead of extending them). It is somewhat similar to implementing a custom control based off a Grid with numerous VisualElements added in, while extending with custom logic.

举个例子，如何构建一个在构造器接受一个标签的自定义按钮？创建一个组合了一个带有标签的RaisedButton的自定义按钮，而不是扩展 RaisedButton 。

For example, how do you build a CustomButton that takes a label in the constructor? Create a CustomButton that composes a ElevatedButton with a label, rather than by extending ElevatedButton:

class CustomButton extends StatelessWidget {
  final String label;

  CustomButton(this.label);

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(onPressed: () {}, child: Text(label));
  }
}

然后就可以像使用其他 Flutter widget 一样使用这个自定义按钮。

Then use CustomButton, just as you’d use any other Flutter widget:

@override
Widget build(BuildContext context) {
  return Center(
    child: CustomButton("Hello"),
  );
}

Navigation

如何在页面之间导航？

How do I navigate between pages?

在 Xamarin.Forms 中，NavigationPage 类提供了一个阶级式的导航方式，让用户可以在页面之间来回进行跳转。

In Xamarin.Forms, the NavigationPage class provides a hierarchical navigation experience where the user is able to navigate through pages, forwards and backwards.

Flutter 也有类似的实现，使用了一个导航器（Navigator）和路由（Routes）。一个路由是一个应用程序里一个页面的抽象，而一个导航器是一个管理路由的 widget。

Flutter has a similar implementation, using a Navigator and Routes. A Route is an abstraction for a Page of an app, and a Navigator is a widget that manages routes.

一个路由大致上映射到一个页面。导航器以类似 Xamarin.Forms NavigationPage 的方式工作，在里面可以 push() 和 pop() 路由，依赖于你是否想导航到一个视图，或者从它返回。

A route dd maps to a Page. The navigator works in a similar way to the Xamarin.Forms NavigationPage, in that it can push() and pop() routes depending on whether you want to navigate to, or back from, a view.

在页面间导航，你有几个选择：

To navigate between pages, you have a couple options:

Specify a Map of route names. (MaterialApp)
Directly navigate to a route. (WidgetApp)
指定路由名称的一个映射。（MaterialApp）
直接导航到一个路由。（WidgetApp）

接下来构建一个映射的示例。

The following example builds a Map.

void main() {
  runApp(MaterialApp(
    home: MyAppHome(), // becomes the route named '/'
    routes: <String, WidgetBuilder> {
      '/a': (BuildContext context) => MyPage(title: 'page A'),
      '/b': (BuildContext context) => MyPage(title: 'page B'),
      '/c': (BuildContext context) => MyPage(title: 'page C'),
    },
  ));
}

通过推入一个路由的名称到导航器来导航到这个路由。

Navigate to a route by pushing its name to the Navigator.

Navigator.of(context).pushNamed('/b');

导航器是一个管理你的应用程序的路由的堆栈。把一个路由推入堆栈可以移动到这个路由，而从堆栈弹出一个路由可以返回到前一个路由。这是通过等待被 push() 返回的 未来（Future） 来完成的。

The Navigator is a stack that manages your app’s routes. Pushing a route to the stack moves to that route. Popping a route from the stack, returns to the previous route. This is done by awaiting on the Future returned by push().

Async/await 与 .NET 的实现非常类似，并且是在 Async UI中有更详尽的解释。

Async/await is very similar to the .NET implementation and is explained in more detail in Async UI.

举个例子，要开始一个让用户选择他们的定位的 定位（location） 路由，你需要做以下步骤：

For example, to start a location route that lets the user select their location, you might do the following:

Map coordinates = await Navigator.of(context).pushNamed('/location');

然后，在你的“定位”路由里，一旦用户选择他们的定位，使用结果来 pop() 这个堆栈。

And then, inside your ‘location’ route, once the user has selected their location, pop the stack with the result:

Navigator.of(context).pop({"lat":43.821757,"long":-79.226392});

如何导航到其它应用程序？

How do I navigate to another app?

在 Xamarin.Forms 中，需要用指定的 URI 协议并使用 Device.OpenUrl("mailto://") 来传送用户到其它应用程序。

In Xamarin.Forms, to send the user to another application, you use a specific URI scheme, using Device.OpenUrl("mailto://")

为了在 Flutter 中实现这个功能，需要创建一个原生平台集成，或者使用已有的插件，比如 url_launcher，可与在 [pub.dev 上的许多其他包一起使用。

To implement this functionality in Flutter, create a native platform integration, or use an existing plugin, such as url_launcher, available with many other packages on pub.dev.

异步 UI

Async UI

在 Flutter 中有什么是跟 Device.BeginOnMainThread() 方法是相等的？

What is the equivalent of Device.BeginOnMainThread() in Flutter?

Dart 拥有一个单线程执行模型，支持“隔离” （在另一个线程上运行Dart代码的方法）、事件循环和异步编程。除非生成一个“隔离”，否则您的Dart代码会在主UI线程中运行，并由一个事件循环来驱动。

Dart 的单线程模型并不意味着需要以会导致UI冻结的阻塞操作方式来运行所有内容。更多地像 Xamarin.Forms 一样需要让 UI 线程保持空闲。您将使用“async”/“wait”来执行任务，其中必须等待响应。

Dart’s single-threaded model doesn’t mean you need to run everything as a blocking operation that causes the UI to freeze. Much like Xamarin.Forms, you need to keep the UI thread free. You would use async/await to perform tasks, where you must wait for the response.

在 Flutter 中，使用 Dart 语言提供的异步工具（也称为 async/await）来执行异步工作。这跟 C# 很像，并且对于 Xamarin.Forms 开发者来说应该是非常容易使用的。

In Flutter, use the asynchronous facilities that the Dart language provides, also named async/await, to perform asynchronous work. This is very similar to C# and should be very easy to use for any Xamarin.Forms developer.

例如，您可以使用 async/await 运行网络请求代码，而不会导致UI挂起，并让Dart完成繁重的工作：

For example, you can run network code without causing the UI to hang by using async/await and letting Dart do the heavy lifting:

loadData() async {
  String dataURL = "https://jsonplaceholder.typicode.com/posts";
  http.Response response = await http.get(dataURL);
  setState(() {
    widgets = jsonDecode(response.body);
  });
}

一旦完成等待的网络调用后，通过调用 setState() 更新UI，这将触发 widget 子树的重新构建并更新数据。

Once the awaited network call is done, update the UI by calling setState(), which triggers a rebuild of the widget sub-tree and updates the data.

下面的实例异步加载数据并在一个 ListView 中显示：

The following example loads data asynchronously and displays it in a ListView:

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List widgets = [];

  @override
  void initState() {
    super.initState();
    loadData();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: ListView.builder(
          itemCount: widgets.length,
          itemBuilder: (BuildContext context, int position) {
            return getRow(position);
          }));
  }

  Widget getRow(int i) {
    return Padding(
      padding: EdgeInsets.all(10.0),
      child: Text("Row ${widgets[i]["title"]}")
    );
  }

  loadData() async {
    String dataURL = "https://jsonplaceholder.typicode.com/posts";
    http.Response response = await http.get(dataURL);
    setState(() {
      widgets = jsonDecode(response.body);
    });
  }
}

有关在后台工作、以及 Flutter 与 Android 的不同之处的更多信息，请参考下一节。

Refer to the next section for more information on doing work in the background, and how Flutter differs from Android.

如何将工作转移到后台线程？

How do you move work to a background thread?

因为 Flutter 是单线程的，并且运行一个事件循环，所以您不必担心线程管理或产生后台线程。这一点与 Xamarin.Forms 非常相似。如果您正在做 I/O 密集型的工作，比如磁盘访问或网络调用，那么您可以安全地使用 async/await，这样就一切就绪了。

Since Flutter is single threaded and runs an event loop, you don’t have to worry about thread management or spawning background threads. This is very similar to Xamarin.Forms. If you’re doing I/O-bound work, such as disk access or a network call, then you can safely use async/await and you’re all set.

另一方面，如果您需要做计算密集型的工作，使CPU保持忙碌，那么您希望将它移动到“隔离”状态，以避免阻塞事件循环，就像您将任何类型的工作放在主线程之外一样。这类似于通过 Xamarin.Forms 中的 Task.Run() 将内容移动到另一个线程。

If, on the other hand, you need to do computationally intensive work that keeps the CPU busy, you want to move it to an Isolate to avoid blocking the event loop, like you would keep any sort of work out of the main thread. This is similar to when you move things to a different thread via Task.Run() in Xamarin.Forms.

对于 I/O 密集型的工作，将函数声明为一个 异步 函数，并在函数内部 等待 长时间运行的任务：

For I/O-bound work, declare the function as an async function, and await on long-running tasks inside the function:

loadData() async {
  String dataURL = "https://jsonplaceholder.typicode.com/posts";
  http.Response response = await http.get(dataURL);
  setState(() {
    widgets = jsonDecode(response.body);
  });
}

这是您通常执行网络或数据库调用的方式，它们都是I/O操作。

This is how you would typically do network or database calls, which are both I/O operations.

然而，有时您可能正在处理大量数据而UI挂起了。在 Flutter 中，使用隔离来利用多个CPU内核来执行长时间运行或计算密集型任务。

隔离线程是独立的执行线程，不与主执行内存堆共享任何内存。这是与 Task.Run() 的区别。这意味着您不能从主线程访问变量，也不能通过调用 setState() 更新UI。

Isolates are separate execution threads that do not share any memory with the main execution memory heap. This is a difference between Task.Run(). This means you can’t access variables from the main thread, or update your UI by calling setState().

下面的示例以简单的方式展示了如何将数据共享回主线程以更新UI。

The following example shows, in a simple isolate, how to share data back to the main thread to update the UI.

loadData() async {
  ReceivePort receivePort = ReceivePort();
  await Isolate.spawn(dataLoader, receivePort.sendPort);

  // The 'echo' isolate sends its SendPort as the first message.
  SendPort sendPort = await receivePort.first;

  List msg = await sendReceive(
    sendPort,
    "https://jsonplaceholder.typicode.com/posts",
  );

  setState(() {
    widgets = msg;
  });
}

// The entry point for the isolate.
static dataLoader(SendPort sendPort) async {
  // Open the ReceivePort for incoming messages.
  ReceivePort port = ReceivePort();

  // Notify any other isolates what port this isolate listens to.
  sendPort.send(port.sendPort);

  await for (var msg in port) {
    String data = msg[0];
    SendPort replyTo = msg[1];

    String dataURL = data;
    http.Response response = await http.get(dataURL);
    // Lots of JSON to parse
    replyTo.send(jsonDecode(response.body));
  }
}

Future sendReceive(SendPort port, msg) {
  ReceivePort response = ReceivePort();
  port.send([msg, response.sendPort]);
  return response.first;
}

在这里，dataLoader() 是在它自己单独的执行线程中运行的隔离。在隔离中，您可以执行更多的CPU密集型处理（例如，解析大型JSON），或者执行计算密集型数学，如加密或信号处理。

你可以运行下面这个完整的例子：

You can run the full example below:

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'dart:async';
import 'dart:isolate';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List widgets = [];

  @override
  void initState() {
    super.initState();
    loadData();
  }

  showLoadingDialog() {
    if (widgets.length == 0) {
      return true;
    }

    return false;
  }

  getBody() {
    if (showLoadingDialog()) {
      return getProgressDialog();
    } else {
      return getListView();
    }
  }

  getProgressDialog() {
    return Center(child: CircularProgressIndicator());
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        appBar: AppBar(
          title: Text("Sample App"),
        ),
        body: getBody());
  }

  ListView getListView() => ListView.builder(
      itemCount: widgets.length,
      itemBuilder: (BuildContext context, int position) {
        return getRow(position);
      });

  Widget getRow(int i) {
    return Padding(
      padding: EdgeInsets.all(10.0),
      child: Text("Row ${widgets[i]["title"]}"),
    );
  }

  loadData() async {
    ReceivePort receivePort = ReceivePort();
    await Isolate.spawn(dataLoader, receivePort.sendPort);

    // The 'echo' isolate sends its SendPort as the first message.
    SendPort sendPort = await receivePort.first;

    List msg = await sendReceive(
      sendPort,
      "https://jsonplaceholder.typicode.com/posts",
    );

    setState(() {
      widgets = msg;
    });
  }

  // the entry point for the isolate
  static dataLoader(SendPort sendPort) async {
    // Open the ReceivePort for incoming messages.
    ReceivePort port = ReceivePort();

    // Notify any other isolates what port this isolate listens to.
    sendPort.send(port.sendPort);

    await for (var msg in port) {
      String data = msg[0];
      SendPort replyTo = msg[1];

      String dataURL = data;
      http.Response response = await http.get(dataURL);
      // Lots of JSON to parse
      replyTo.send(jsonDecode(response.body));
    }
  }

  Future sendReceive(SendPort port, msg) {
    ReceivePort response = ReceivePort();
    port.send([msg, response.sendPort]);
    return response.first;
  }
}

如何发送一个网络请求？

How do I make network requests?

在 Xamarin.Forms 中，你可以使用 HttpClient。当您使用流行的 http package 包时，在 Flutter 中进行网络调用就很容易了。这将抽象出许多您通常可能自己实现的网络，从而使网络调用变简化。

In Xamarin.Forms you would use HttpClient. Making a network call in Flutter is easy when you use the popular http package. This abstracts away a lot of the networking that you might normally implement yourself, making it simple to make network calls.

要使用 http 包，请将它添加到 pubspec.yaml 文件中的依赖项中：

To use the http package, add it to your dependencies in pubspec.yaml:

dependencies:
  ...
  http: ^0.11.3+16

To make a network request, call await on the async function http.get():

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
[...]
  loadData() async {
    String dataURL = "https://jsonplaceholder.typicode.com/posts";
    http.Response response = await http.get(dataURL);
    setState(() {
      widgets = jsonDecode(response.body);
    });
  }
}

如何显示长时间运行的任务的进度？

How do I show the progress for a long-running task?

在 Xamarin.Forms 中常会创建一个加载指示器，可以直接在XAML中创建，也可以通过第三方插件创建，比如 AcrDialogs。

In Xamarin.Forms you would typically create a loading indicator, either directly in XAML or through a 3rd party plugin such as AcrDialogs.

在 Flutter 中，使用一个 加载指示器（ ProgressIndicator）widget。通过一个布尔标志控制何时渲染来以编程方式显示进度。告诉 Flutter 在长时间运行的任务开始之前更新它的状态，并在任务结束后隐藏它。

在下面的示例中，build 函数被分成三个不同的函数。如果 showLoadingDialog() 是 true （即当widgets.length == 0时）就会渲染出 进度指示器。另一方面，用网络调用返回的数据渲染 列表视图（ListView）。

In the following example, the build function is separated into three different functions. If showLoadingDialog() is true (when widgets.length == 0), then render the ProgressIndicator. Otherwise, render the ListView with the data returned from a network call.

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List widgets = [];

  @override
  void initState() {
    super.initState();
    loadData();
  }

  showLoadingDialog() {
    return widgets.length == 0;
  }

  getBody() {
    if (showLoadingDialog()) {
      return getProgressDialog();
    } else {
      return getListView();
    }
  }

  getProgressDialog() {
    return Center(child: CircularProgressIndicator());
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        appBar: AppBar(
          title: Text("Sample App"),
        ),
        body: getBody());
  }

  ListView getListView() => ListView.builder(
      itemCount: widgets.length,
      itemBuilder: (BuildContext context, int position) {
        return getRow(position);
      });

  Widget getRow(int i) {
    return Padding(
      padding: EdgeInsets.all(10.0),
      child: Text("Row ${widgets[i]["title"]}"),
    );
  }

  loadData() async {
    String dataURL = "https://jsonplaceholder.typicode.com/posts";
    http.Response response = await http.get(dataURL);
    setState(() {
      widgets = jsonDecode(response.body);
    });
  }
}

项目结构与资源

Project structure & resources

如何储存我的图片文件？

Where do I store my image files?

Xamarin.Forms 没有独立于平台的存储图像的方法，您必须放置图片在 iOS 的 xcasset 文件夹, 或 Android 的 drawable 文件夹中。

Xamarin.Forms has no platform independent way of storing images, you had to place images in the iOS xcasset folder or on Android, in the various drawable folders.

Android和iOS将资源（resources）和资产（assets）视为不同的项目，而 Flutter 应用程序只有资产（assets）。 Resources/drawable-* 文件夹中的所有资源都放在一个 Flutter 的资产 (assets) 文件夹中。

While Android and iOS treat resources and assets as distinct items, Flutter apps have only assets. All resources that would live in the Resources/drawable-* folders on Android, are placed in an assets folder for Flutter.

Flutter 遵循一种与 iOS 类似的简单的基于密度（density-based）的格式。资产可能是 1.0x、2.0x、3.0x 或任何其他倍数。Flutter 没有 dp，但是有逻辑像素，这基本上是与设备无关像素相同。用所谓 devicePixelRatio 表示单个逻辑像素中物理像素的比例。

与 Android 的密度桶相等的是：

The equivalent to Android’s density buckets are:

Android density qualifier	Flutter pixel ratio
`ldpi`	`0.75x`
`mdpi`	`1.0x`
`hdpi`	`1.5x`
`xhdpi`	`2.0x`
`xxhdpi`	`3.0x`
`xxxhdpi`	`4.0x`

资产位于任意文件夹中— Flutter 没有预定义的文件夹结构。在 pubspec.yaml 文件中声明资产(带有位置)，Flutter 就会得到它们。

Assets are located in any arbitrary folder—Flutter has no predefined folder structure. You declare the assets (with location) in the pubspec.yaml file, and Flutter picks them up.

注意，在 Flutter 1.0 beta 2 之前的版本中，Flutter 中定义的资产并不能从原生一侧访问，反之亦然，原生资产和资源对 Flutter 无效，就像他们被放在单独的文件夹中。

在 Flutter beta 2 版本中，资产都被存储在原生的资产文件夹中，并且可以通过 Android 的资产管理器（AssetManager） 从原生一侧被访问。

As of Flutter beta 2, assets are stored in the native asset folder, and are accessed on the native side using Android’s AssetManager:

在 Flutter beta 2 版本中，Flutter 仍然不能访问原生资源，也不能访问原生资产。

As of Flutter beta 2, Flutter still cannot access native resources, nor it can access native assets.

例如，如果要新建一个新的名为 my_icon.png 的图像资产到我们的 Flutter 项目，并决定它应该放在一个被我们随意命名为 images 的文件夹中，你需要把基础图像（1.0x）放到 images 文件夹中，而所有的其他变量的文件放在以与之对应的比率乘数命名的子文件夹中：

images/my_icon.png       // Base: 1.0x image
images/2.0x/my_icon.png  // 2.0x image
images/3.0x/my_icon.png  // 3.0x image

接下来，您需要在您的 pubspec.yaml 文件中声明这些图像：

Next, you’ll need to declare these images in your pubspec.yaml file:

assets:
 - images/my_icon.jpeg

之后就可以用 AssetImage 来访问你的图像了：

You can then access your images using AssetImage:

return AssetImage("images/a_dot_burr.jpeg");

或者可以直接在一个 Image widget 中访问：

or directly in an Image widget:

@override
Widget build(BuildContext context) {
  return Image.asset("images/my_image.png");
}

更多详尽的信息可以在在 Flutter 中添加资产和图像中找到。

More detailed information can be found in Adding assets and images.

在哪里存储字符串？如何处理本地化？

Where do I store strings? How do I handle localization?

与 .NET 拥有 resx 文件不同，Flutter 目前没有一个专门的字符串类资源系统。此时，最佳实践是将复制文本作为静态字段保存在类中，并从那里访问它们。举个例子：

Unlike .NET which has resx files, Flutter currently doesn’t have a dedicated resources-like system for strings. At the moment, the best practice is to hold your copy text in a class as static fields and accessing them from there. For example:

class Strings {
  static String welcomeMessage = "Welcome To Flutter";
}

那么在你的代码中，你可以像这样访问你的字符串：

Then in your code, you can access your strings as such:

Text(Strings.welcomeMessage)

默认情况下，Flutter 的字符串只支持美式英语。如果你需要添加其他语音的支持，可以包含 flutter_localizations 包。你可能还需要添加 Dart的 intl 包来使用 i10n 装置，例如日期、时间的格式化。

dependencies:
  # ...
  flutter_localizations:
    sdk: flutter
  intl: "^0.15.6"

使用 flutter_localizations 包时，要在应用程序的 widget 上指定 localizationsDelegates 和 supportedLocales：

To use the flutter_localizations package, specify the localizationsDelegates and supportedLocales on the app widget:

import 'package:flutter_localizations/flutter_localizations.dart';

MaterialApp(
 localizationsDelegates: const [
   // Add app-specific localization delegate[s] here.
   GlobalMaterialLocalizations.delegate,
   GlobalWidgetsLocalizations.delegate,
 ],
 supportedLocales: const [
    Locale('en', 'US'), // English
    Locale('he', 'IL'), // Hebrew
    // ... other locales the app supports
  ],
  // ...
)

委托包含实际的本地化值，而 supportedLocales 定义了应用程序支持哪些本地化。上面的示例使用了一个 MaterialApp，因此它为基本 widget 本地化值提供了一个 GlobalWidgetsLocalizations，为 Material widget 的本地化提供了一个 MaterialWidgetsLocalizations。如果你的应用程序使用 WidgetsApp ，你就不需要后者了。请注意，这两个委托包含“默认”值，但是如果您希望它们也本地化，则需要为您自己的应用程序的可本地化副本提供一个或多个委托。

初始化后， WidgetsApp （或 MaterialApp）为您创建一个 Localizations widget，其中包含您指定的委托。设备的当前区域设置总是可以从当前上下文的 Localizations widget (以 Locale 对象的形式)或使用 Window.locale 访问。

要访问本地化的资源，请使用 Localizations.of() 方法去访问一个由给定委托提供的特定本地化类。使用 intl_translation 包将可翻译的文本拷贝到 arb 文件中进行翻译，并将其导入到应用程序中与 intl 一起使用。

要了解更多关于 Flutter 国际化和本地化的细节，请查阅国际化指南，它有带和不带 intl 包的示例代码。

For further details on internationalization and localization in Flutter, see the internationalization guide, which has sample code with and without the intl package.

我的项目文件在哪里？

Where is my project file?

Xamarin.Forms 中有一个 csproj 文件。在 Flutter 中最接近的它的是 pubspec.yaml，其中包含包依赖项和各种项目细节。就像 .NET Standard，相同目录中的文件被认为是项目的一部分。

In Xamarin.Forms you will have a csproj file. The closest equivalent in Flutter is pubspec.yaml, which contains package dependencies and various project details. Similar to .NET Standard, files within the same directory are considered part of the project.

Nuget 的等价物是什么？如何添加依赖项？

What is the equivalent of Nuget? How do I add dependencies?

在 .NET 生态系统中，原生 Xamarin 项目和 Xamarin.Forms 项目都可以访问 Nuget 和内置的包管理系统。 Flutter 应用程序包含一个原生Android 应用程序，原生 iOS 应用程序和 Flutter 应用程序。

In the .NET eco-system, native Xamarin projects and Xamarin.Forms projects had access to Nuget and the inbuilt package management system. Flutter apps contain a native Android app, native iOS app and Flutter app.

在Android中，您可以通过向Gradle添加构建脚本来添加依赖项。而在iOS中，你可以通过添加到 Podfile 来添加依赖项。

In Android, you add dependencies by adding to your Gradle build script. In iOS, you add dependencies by adding to your Podfile.

Flutter 使用 Dart 自己的构建系统和 Pub 包管理器。这些工具将原生 Android 和 iOS 封装应用程序的构建委托给各自的构建系统。

Flutter uses Dart’s own build system, and the Pub package manager. The tools delegate the building of the native Android and iOS wrapper apps to the respective build systems.

一般来说，使用 pubspec.yaml 来声明要在 Flutter 中使用的外部依赖项。 pub.dev 是一个寻找 Flutter 包的好地方。

In general, use pubspec.yaml to declare external dependencies to use in Flutter. A good place to find Flutter packages is on pub.dev.

应用程序生命周期

Application lifecycle

如何侦听应用程序的生命周期事件？

How do I listen to application lifecycle events?

在 Xamarin.Forms 中，拥有一个包含 OnStart、OnResume 和 OnSleep 的应用程序。在 Flutter 中，您可以通过挂钩到 WidgetsBinding 观察者并监听 didChangeAppLifecycleState() 更改事件来监听类似的生命周期事件。

In Xamarin.Forms, you have an Application that contains OnStart, OnResume and OnSleep. In Flutter you can instead listen to similar lifecycle events by hooking into the WidgetsBinding observer and listening to the didChangeAppLifecycleState() change event.

可观察的生命周期事件有:

The observable lifecycle events are:

`inactive`

* `inactive` — 应用程序处于非活动状态，并且没有接收用户输入。此事件仅适用于iOS。

The application is in an inactive state and is not receiving user input. This event is iOS only.

`paused`

应用程序当前对用户不可见，不响应用户输入，但是在后台运行。

The application is not currently visible to the user, is not responding to user input, but is running in the background.

`resumed`

应用程序是可见的，并响应用户输入。

The application is visible and responding to user input.

`suspending`

应用程序暂时暂停。此事件仅限Android。

The application is suspended momentarily. This event is Android only.

有关这些状态的含义的更多细节，可参考 AppLifecycleStatus 文档。

For more details on the meaning of these states, see the AppLifecycleStatus documentation.

布局

Layouts

什么东西与 StackLayout 等效?

What is the equivalent of a StackLayout?

在 Xamarin.Forms 中，可以创建一个带水平或垂直方向的 StackLayout 。 Flutter 也有类似的方法，不过您将使用 Row 或 Column widget。

In Xamarin.Forms you can create a StackLayout with an Orientation of horizontal or vertical. Flutter has a similar approach, however you would use the Row or Column widgets.

如果您注意到除了“Row” 和“Column” widget 之外，这两个代码示例是相同的。这些子元素是相同的，可以利用这个特性开发丰富的布局，这些布局可以随着时间的推移而改变。

@override
Widget build(BuildContext context) {
  return Row(
    mainAxisAlignment: MainAxisAlignment.center,
    children: <Widget>[
      Text('Row One'),
      Text('Row Two'),
      Text('Row Three'),
      Text('Row Four'),
    ],
  );
}

@override
Widget build(BuildContext context) {
  return Column(
    mainAxisAlignment: MainAxisAlignment.center,
    children: <Widget>[
      Text('Column One'),
      Text('Column Two'),
      Text('Column Three'),
      Text('Column Four'),
    ],
  );
}

什么东西与网格（Grid）等价?

What is the equivalent of a Grid?

与Grid最接近的对等项是 GridView。这比您在 Xamarin.Forms 中习惯使用的功能强大得多。 GridView 在内容超出其可视空间时自动滚动。

The closest equivalent of a Grid would be a GridView. This is much more powerful than what you are used to in Xamarin.Forms. A GridView provides automatic scrolling when the content exceeds its viewable space.

  GridView.count(
    // Create a grid with 2 columns. If you change the scrollDirection to
    // horizontal, this would produce 2 rows.
    crossAxisCount: 2,
    // Generate 100 widgets that display their index in the List
    children: List.generate(100, (index) {
      return Center(
        child: Text(
          'Item $index',
          style: Theme.of(context).textTheme.headline,
        ),
      );
    }),
  );

您可能在 Xamarin.Forms 中使用 Grid 来实现覆盖其他 widget 的 widget。在 Flutter 中，您可以使用 Stack widget 来完成这一操作。

You might have used a Grid in Xamarin.Forms to implement widgets that overlay other widgets. In Flutter, you accomplish this with the Stack widget

这个示例创建了两个相互重叠的图标。

This sample creates two icons that overlap each other.

child: Stack(
  children: <Widget>[
    Icon(Icons.add_box, size: 24.0, color: const Color.fromRGBO(0,0,0,1.0)),
    Positioned(
      left: 10.0,
      child: Icon(Icons.add_circle, size: 24.0, color: const Color.fromRGBO(0,0,0,1.0)),
    ),
  ],
),

有什么等同于 ScrollView ？

What is the equivalent of a ScrollView?

在 Xamarin.Forms 中，ScrollView 封装了 VisualElement，如果内容大于设备屏幕，它就会滚动。

In Xamarin.Forms, a ScrollView wraps around a VisualElement and, if the content is larger than the device screen, it scrolls.

在 Flutter 中，最接近的是 SingleChildScrollView widget。您只需用想要可滚动的内容来填充 widget。

In Flutter, the closest match is the SingleChildScrollView widget. You simply fill the Widget with the content that you want to be scrollable.

@override
Widget build(BuildContext context) {
  return SingleChildScrollView(
    child: Text('Long Content'),
  );
}

如果您想在滚动条中包含许多项，即使是不同的Widget类型，也可以使用 ListView。这可能看起来有点过火，但在 Flutter 中，它比 Xamarin.Forms 的回到平台特定控件的 ListView 优化得多，松散得多。

If you have many items you want to wrap in a scroll, even of different Widget types, you might want to use a ListView. This might seem like overkill, but in Flutter this is far more optimized and less intensive than a Xamarin.Forms ListView, which is backing on to platform specific controls.

@override
Widget build(BuildContext context) {
  return ListView(
    children: <Widget>[
      Text('Row One'),
      Text('Row Two'),
      Text('Row Three'),
      Text('Row Four'),
    ],
  );
}

在 Flutter 中如何处理横向过渡 ?

How do I handle landscape transitions in Flutter?

通过在 AndroidManifest.xml 中设置 configChanges 属性，可以自动处理横向转换。

Landscape transitions can be handled automatically by setting the configChanges property in the AndroidManifest.xml:

android:configChanges="orientation|screenSize"

手势检测和触摸事件处理

Gesture detection and touch event handling

How do I add GestureRecognizers to a widget in Flutter?

在 Xamarin.Forms 中，元素（Element） 可能包含一个可供附加（attach）的单击事件。许多元素还包含一个与此事件关联的 命令 。或者你可以使用 TapGestureRecognizer。在 Flutter 中有两种非常相似的方式：

In Xamarin.Forms, Elements might contain a click event you can attach to. Many elements also contain a Command that is tied to this event. Alternatively you would use the TapGestureRecognizer. In Flutter there are two very similar ways:

如果 widget 支持事件发现（detection），那么可以将函数传递给它并在函数中处理它：
If the widget supports event detection, pass a function to it and handle it in the function. For example, the ElevatedButton has an onPressed parameter:
```
@override
Widget build(BuildContext context) {
  return ElevatedButton(
      onPressed: () {
        print("click");
      },
      child: Text("Button"));
}
```
If the widget doesn’t support event detection, wrap the widget in a GestureDetector and pass a function to the onTap parameter.

如果 widget 不支持事件发现，则将 widget 封装在手势检测器（GestureDetector）中，并将函数传递给 onTap 参数。

<!-- skip -->
```dart
class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
        body: Center(
      child: GestureDetector(
        child: FlutterLogo(
          size: 200.0,
        ),
        onTap: () {
          print("tap");
        },
      ),
    ));
  }
}
```

我如何处理 widget 上的其他手势？

How do I handle other gestures on widgets?

在 Xamarin.Forms 中你可以在 VisualElement 中添加一个 手势识别器（GestureRecognizer）。您通常只能使用 TapGestureRecognizer、PinchGestureRecognizer、PanGestureRecognizer、， SwipeGestureRecognizer、DragGestureRecognizer 和 DropGestureRecognizer，除非您构建了自己的实现。

In Xamarin.Forms you would add a GestureRecognizer to the View. You would normally be limited to TapGestureRecognizer, PinchGestureRecognizer, PanGestureRecognizer, SwipeGestureRecognizer, DragGestureRecognizer and DropGestureRecognizer unless you built your own.

在Flutter中，使用手势检测器，你可以监听到各种各样的手势，比如:

In Flutter, using the GestureDetector, you can listen to a wide range of Gestures such as:

单击
Tap

`onTapDown`

当指尖在特定位置与屏幕接触产生点击事件。

A pointer that might cause a tap has contacted the screen at a particular location.

`onTapUp`

当指尖触发的点击事件已经停止在特定位置与屏幕接触。

A pointer that triggers a tap has stopped contacting the screen at a particular location.

`onTap`

一个点击事件已经发生

A tap has occurred.

`onTapCancel`

触发了 `onTapDown` 事件之后的指尖没有导致点击事件。

The pointer that previously triggered the `onTapDown` won't cause a tap.

双击
Double tap

`onDoubleTap`

用户在同一位置连续快速点击屏幕两次。

The user tapped the screen at the same location twice in quick succession.

长按
Long press

`onLongPress`

指尖长时间保持与屏幕在同一位置的接触。

A pointer has remained in contact with the screen at the same location for a long period of time.

垂直拖动
Vertical drag

`onVerticalDragStart`

指尖与屏幕接触后，可能开始垂直移动。

A pointer has contacted the screen and might begin to move vertically.

`onVerticalDragUpdate`

指尖与屏幕接触并在垂直方向上移动得更远。

A pointer in contact with the screen has moved further in the vertical direction.

`onVerticalDragEnd`

指尖在之前与屏幕接触并垂直移动，当不再与屏幕接触时触发这个事件。当它停止与屏幕接触时，它会以特定的速度移动。

A pointer that was previously in contact with the screen and moving vertically is no longer in contact with the screen and was moving at a specific velocity when it stopped contacting the screen.

水平拖动
Horizontal drag

`onHorizontalDragStart`

指尖与屏幕接触，开始水平移动时触发。

A pointer has contacted the screen and might begin to move horizontally.

`onHorizontalDragUpdate`

指尖与屏幕接触并在水平方向上移动得更远。

A pointer in contact with the screen has moved further in the horizontal direction.

`onHorizontalDragEnd`

指尖在之前与屏幕接触并水平移动，当不再与屏幕接触时会触发这个事件。当它停止与屏幕接触时，它正在以特定的速度移动。

A pointer that was previously in contact with the screen and moving horizontally is no longer in contact with the screen and was moving at a specific velocity when it stopped contacting the screen.

下面的例子展示了一个手势检测器，它可以在双击下旋转 Flutter 的 logo：

The following example shows a GestureDetector that rotates the Flutter logo on a double tap:

AnimationController controller;
CurvedAnimation curve;

@override
void initState() {
  super.initState();
  controller = AnimationController(duration: const Duration(milliseconds: 2000), vsync: this);
  curve = CurvedAnimation(parent: controller, curve: Curves.easeIn);
}

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
        body: Center(
          child: GestureDetector(
            child: RotationTransition(
                turns: curve,
                child: FlutterLogo(
                  size: 200.0,
                )),
            onDoubleTap: () {
              if (controller.isCompleted) {
                controller.reverse();
              } else {
                controller.forward();
              }
            },
        ),
    ));
  }
}

列表视图和适配器

Listviews and adapters

在 Flutter 中，与列表视图等价的是什么？

What is the equivalent to a ListView in Flutter?

在Flutter中与 ListView 等价的是……一个 ListView！

The equivalent to a ListView in Flutter is … a ListView!

在一个 Xamarin.Forms 的 ListView 中，你可以创建一个 ViewCell 可能还有一个 DataTemplateSelector 并将其传递到 ListView 中，该视图将用您的DataTemplateSelector 或者 ViewCell 的返回数据渲染每一行。但是，您通常必须确保打开单元格回收，否则会遇到内存问题和会使滚动速度变慢。

In a Xamarin.Forms ListView, you create a ViewCell and possibly a DataTemplateSelector and pass it into the ListView, which renders each row with what your DataTemplateSelector or ViewCell returns. However, you often have to make sure you turn on Cell Recycling otherwise you will run into memory issues and slow scrolling speeds.

由于 Flutter 的不可变的 widget 模式，您将一个 widget 列表传递给您的 ListView，Flutter 会负责确保滚动速度快且平稳。

Due to Flutter’s immutable widget pattern, you pass a list of widgets to your ListView, and Flutter takes care of making sure that scrolling is fast and smooth.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: ListView(children: _getListData()),
    );
  }

  _getListData() {
    List<Widget> widgets = [];
    for (int i = 0; i < 100; i++) {
      widgets.add(Padding(padding: EdgeInsets.all(10.0), child: Text("Row $i")));
    }
    return widgets;
  }
}

如何知道哪个列表项被点击了？

How do I know which list item has been clicked?

在 Xamarin.Forms 中，ListView 拥有一个ItemTapped 方法能找出哪个列表项被单击了。您可能还使用了许多其他技术，比如检查 SelectedItem 或 EventToCommand 的行为何时会发生更改。

In Xamarin.Forms, the ListView has an ItemTapped method to find out which item was clicked. There are many other techniques you might have used such as checking when SelectedItem or EventToCommand behaviors change.

在 Flutter 中，使用传入 widget 提供的触摸处理。

In Flutter, use the touch handling provided by the passed-in widgets.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: ListView(children: _getListData()),
    );
  }

  _getListData() {
    List<Widget> widgets = [];
    for (int i = 0; i < 100; i++) {
      widgets.add(GestureDetector(
        child: Padding(
            padding: EdgeInsets.all(10.0),
            child: Text("Row $i")),
        onTap: () {
          print('row tapped');
        },
      ));
    }
    return widgets;
  }
}

如何动态更新 ListView ?

How do I update a ListView dynamically?

在 Xamarin.Forms 中，如果将 ItemsSource 属性绑定到一个 ObservableCollection，就只需要更新视图模型中的列表。另一种方法是，你可以给属性 ItemsSource 分配一个新的 列表 。

In Xamarin.Forms, if you bound the ItemsSource property to an ObservableCollection you would just update the list in your ViewModel. Alternatively, you could assign a new List to the ItemSource property.

在 Flutter 中，情况略有不同。如果您要在 setState() 内更新 widget 列表，您将很快看到您的数据在视觉上没有发生变化。这是因为当 setState() 被调用时，Flutter 的渲染引擎会检查 widget 树是否发生了更改。当它到达您的 ListView 时，会执行 == 检查，并确定这两个 ListView 是相同的。没有任何更改，就不需要更新。

In Flutter, things work a little differently. If you update the list of widgets inside a setState() method, you would quickly see that your data did not change visually. This is because when setState() is called, the Flutter rendering engine looks at the widget tree to see if anything has changed. When it gets to your ListView, it performs a == check, and determines that the two ListViews are the same. Nothing has changed, so no update is required.

要更新 ListView 的有一个简单方法，请在 setState() 中创建一个新 列表 ，并将数据从旧列表复制到新列表。虽然这种方法很简单，但不推荐用于大型数据集，如下例所示。

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List<Widget> widgets = [];

  @override
  void initState() {
    super.initState();
    for (int i = 0; i < 100; i++) {
      widgets.add(getRow(i));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: ListView(children: widgets),
    );
  }

  Widget getRow(int i) {
    return GestureDetector(
      child: Padding(
          padding: EdgeInsets.all(10.0),
          child: Text("Row $i")),
      onTap: () {
        setState(() {
          widgets = List.from(widgets);
          widgets.add(getRow(widgets.length));
          print('row $i');
        });
      },
    );
  }
}

推荐的、高效的、有效的列表构建方法是使用 ListView.Builder。在您有一个动态列表或一个包含大量数据的列表时，这种方法非常棒。这基本上相当于 Android 上的 RecyclerView，它会自动回收列表元素：

The recommended, efficient, and effective way to build a list uses a ListView.Builder. This method is great when you have a dynamic list or a list with very large amounts of data. This is essentially the equivalent of RecyclerView on Android, which automatically recycles list elements for you:

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  List<Widget> widgets = [];

  @override
  void initState() {
    super.initState();
    for (int i = 0; i < 100; i++) {
      widgets.add(getRow(i));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        appBar: AppBar(
          title: Text("Sample App"),
        ),
        body: ListView.builder(
            itemCount: widgets.length,
            itemBuilder: (BuildContext context, int position) {
              return getRow(position);
            }));
  }

  Widget getRow(int i) {
    return GestureDetector(
      child: Padding(
          padding: EdgeInsets.all(10.0),
          child: Text("Row $i")),
      onTap: () {
        setState(() {
          widgets.add(getRow(widgets.length));
          print('row $i');
        });
      },
    );
  }
}

与创建一个“列表视图” 相比，创建一个 ListView.builder 需要接受两个关键参数：列表的初始长度和 ItemBuilder 函数。

Instead of creating a “ListView”, create a ListView.builder that takes two key parameters: the initial length of the list, and an ItemBuilder function.

ItemBuilder 函数类似于 Android 适配器中的 getView 函数；它接受一个位置，并返回您希望的在该位置呈现的行。

The ItemBuilder function is similar to the getView function in an Android adapter; it takes a position, and returns the row you want rendered at that position.

最后，但也是最重要的，要注意 onTap() 函数不再重新创建列表，而是用 .add 添加给它的。

Finally, but most importantly, notice that the onTap() function doesn’t recreate the list anymore, but instead adds to it.

For more information, see Write your first Flutter app, part 1 and Write your first Flutter app, part 2.

文本处理

Working with text

如何在文本（Text） widget 上设置自定义字体?

How do I set custom fonts on my text widgets?

在 Xamarin.Forms 中，您必须在每个原生项目中添加自定义字体。然后在你的 元素 中，你会使用 filename#fontname 给 FontFamily 属性分配这个字体名，而在iOS中只使用 fontname 。

In Xamarin.Forms, you would have to add a custom font in each native project. Then, in your Element you would assign this font name to the FontFamily attribute using filename#fontname and just fontname for iOS.

在 Flutter 中，将字体文件放在一个文件夹中，并在 pubspec.yaml 中引用它，这跟导入图像的方式类似。

In Flutter, place the font file in a folder and reference it in the pubspec.yaml file, similar to how you import images.

fonts:
   - family: MyCustomFont
     fonts:
       - asset: fonts/MyCustomFont.ttf
       - style: italic

Then assign the font to your Text widget:

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(
      title: Text("Sample App"),
    ),
    body: Center(
      child: Text(
        'This is a custom font text',
        style: TextStyle(fontFamily: 'MyCustomFont'),
      ),
    ),
  );
}

如何设置文本 widget 的样式？

How do I style my text widgets?

除了字体，您还可以在文本 widget 上定制其他样式元素。 文本 widget 的样式参数接受一个 TextStyle 对象，您可以在其中定制许多参数，比如:

Along with fonts, you can customize other styling elements on a Text widget. The style parameter of a Text widget takes a TextStyle object, where you can customize many parameters, such as:

color
decoration
decorationColor
decorationStyle
fontFamily
fontSize
fontStyle
fontWeight
hashCode
height
inherit
letterSpacing
textBaseline
wordSpacing

表单录入

Form input

如何检索用户输入？

How do I retrieve user input?

Xamarin.Forms 的元素允许您直接查询元素来确定它的任何属性的状态，或者它被绑定到视图模型中的属性。

Xamarin.Forms elements allow you to directly query the element to determine the state of any of its properties, or whether it’s bound to a property in a ViewModel.

在 Flutter 中检索信息是由专门的 widget 处理的，这是跟原来的习惯不同的。如果你有一个 TextField 或 TextFormField ，你可以提供一个 TextEditingController 来检索用户输入:

Retrieving information in Flutter is handled by specialized widgets and is different than how you are used to. If you have a TextField or a TextFormField, you can supply a TextEditingController to retrieve user input:

class _MyFormState extends State<MyForm> {
  // Create a text controller and use it to retrieve the current value
  // of the TextField.
  final myController = TextEditingController();

  @override
  void dispose() {
    // Clean up the controller when disposing of the widget.
    myController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Retrieve Text Input'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: TextField(
          controller: myController,
        ),
      ),
      floatingActionButton: FloatingActionButton(
        // When the user presses the button, show an alert dialog with the
        // text that the user has typed into our text field.
        onPressed: () {
          return showDialog(
            context: context,
            builder: (context) {
              return AlertDialog(
                // Retrieve the text that the user has entered using the
                // TextEditingController.
                content: Text(myController.text),
              );
            },
          );
        },
        tooltip: 'Show me the value!',
        child: Icon(Icons.text_fields),
      ),
    );
  }
}

你可以在 Flutter 实用教程中的获取文本框的输入值找到更多的信息和完整的代码清单。

You can find more information and the full code listing in Retrieve the value of a text field, from the Flutter cookbook.

在入口的占位符 (Placeholder) 与什么等价？

What is the equivalent of a Placeholder on an Entry?

在 Xamarin.Forms 中，一些元素支持占位符（Placeholder）属性，可以给它赋一个值。如：

In Xamarin.Forms, some Elements support a Placeholder property that you can assign a value to. For example:

  <Entry Placeholder="This is a hint">

在 Flutter 中，通过在文本 widget 的装饰器构造函数参数中添加 InputDecoration 对象，可以轻松地为输入显示“提示”或占位符文本。

In Flutter, you can easily show a “hint” or a placeholder text for your input by adding an InputDecoration object to the decoration constructor parameter for the text widget.

body: Center(
  child: TextField(
    decoration: InputDecoration(hintText: "This is a hint"),
  )
)

如何显示验证错误？

How do I show validation errors?

使用 Xamarin.Forms 时，如果您希望提供验证错误的可视化提示，则需要创建新属性和 虚拟元素（VisualElement） 来包围具有验证错误的元素。

With Xamarin.Forms, if you wished to provide a visual hint of a validation error, you would need to create new properties and VisualElements surrounding the Elements that had validation errors.

在 Flutter 中，我们将 InputDecoration 对象传递给文本 widget 的装饰器构造函数。

In Flutter, you pass through an InputDecoration object to the decoration constructor for the text widget.

然而，您不希望从显示错误开始。相反，当用户输入无效数据时，应该更新状态，并传递一个新的 InputDecoration 对象。

However, you don’t want to start off by showing an error. Instead, when the user has entered invalid data, update the state, and pass a new InputDecoration object.

import 'package:flutter/material.dart';

void main() {
  runApp(SampleApp());
}

class SampleApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: SampleAppPage(),
    );
  }
}

class SampleAppPage extends StatefulWidget {
  SampleAppPage({Key key}) : super(key: key);

  @override
  _SampleAppPageState createState() => _SampleAppPageState();
}

class _SampleAppPageState extends State<SampleAppPage> {
  String _errorText;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Sample App"),
      ),
      body: Center(
        child: TextField(
          onSubmitted: (String text) {
            setState(() {
              if (!isEmail(text)) {
                _errorText = 'Error: This is not an email';
              } else {
                _errorText = null;
              }
            });
          },
          decoration: InputDecoration(hintText: "This is a hint", errorText: _getErrorText()),
        ),
      ),
    );
  }

  _getErrorText() {
    return _errorText;
  }

  bool isEmail(String em) {
    String emailRegexp =
        r'^(([^<>()[\]\\.,;:\s@\"]+(\.[^<>()[\]\\.,;:\s@\"]+)*)|(\".+\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$';

    RegExp regExp = RegExp(emailRegexp);

    return regExp.hasMatch(em);
  }
}

Flutter 插件

Flutter plugins

与硬件、第三方服务和平台交互

Interacting with hardware, third party services, and the platform

应该如何与平台以及平台原生代码交互?

How do I interact with the platform, and with platform native code?

Flutter 不直接在底层平台上运行代码。相反，构成一个 Flutter 应用程序的 Dart 代码是在设备上原生运行的，“绕开”了平台提供的 SDK。这意味着，例如，当您在 Dart 中执行网络请求时，它将直接运行在 Dart 上下文中。在编写原生应用程序时，您通常不会使用 Android 或 iOS 的 API。 Flutter 应用程序仍然作为视图驻留在原生应用程序的 ViewController或 Activity 中，但您不能直接访问这个或原生框架。

Flutter doesn’t run code directly on the underlying platform; rather, the Dart code that makes up a Flutter app is run natively on the device, “sidestepping” the SDK provided by the platform. That means, for example, when you perform a network request in Dart, it runs directly in the Dart context. You don’t use the Android or iOS APIs you normally take advantage of when writing native apps. Your Flutter app is still hosted in a native app’s ViewController or Activity as a view, but you don’t have direct access to this, or the native framework.

这并不意味着 Flutter 应用程序不能与这些原生 API 或您自己的任何原生代码交互。 Flutter 提供平台通道, 可以与托管 Flutter 视图的 ViewController 或 Activity 通信和交换数据。平台通道本质上是一个异步消息传递机制，它将 Dart 代码与 ViewController 或 Activity 宿主以及它所运行的 iOS 或 Android 框架桥接起来。例如，您可以使用平台通道在原生端执行一个方法，或者从设备的传感器检索一些数据。

This doesn’t mean Flutter apps can’t interact with those native APIs, or with any native code you have. Flutter provides platform channels that communicate and exchange data with the ViewController or Activity that hosts your Flutter view. Platform channels are essentially an asynchronous messaging mechanism that bridges the Dart code with the host ViewController or Activity and the iOS or Android framework it runs on. You can use platform channels to execute a method on the native side, or to retrieve some data from the device’s sensors, for example.

除了直接使用平台通道外，您还可以使用各种预制插件，它们封装了针对特定目标的原生代码和Dart代码。例如，您可以使用插件直接从Flutter访问相机交卷和设备相机，而无需编写自己的集成。插件可以在 pub.dev、Dart 和 Flutter 的开源包存储库中找到。有些包可能支持iOS上的本地集成，有些支持Android，还有两者都兼而有之的。

如果在 Pub 上找不到适合您需求的插件，你可以编写自己的插件并在 Pub 上发布。

If you can’t find a plugin on pub.dev that fits your needs, you can write your own, and publish it on pub.dev.

如何访问 GPS 传感器?

How do I access the GPS sensor?

使用 geolocator 社区插件.

Use the geolocator community plugin.

如何访问摄相机？

How do I access the camera?

image_picker 是流行的访问相机的插件。

The image_picker plugin is popular for accessing the camera.

如何通过 Facebook 登录？

How do I log in with Facebook?

To log in with Facebook, use the

使用 flutter_facebook_login 社区插件来通过 Facebook 登录。

flutter_facebook_login community plugin.

如何使用 Firebase 特性？

How do I use Firebase features?

大多数 Firebase 功能被官方插件覆盖。

Most Firebase functions are covered by first party plugins. These plugins are first-party integrations, maintained by the Flutter team:

firebase_admob for Firebase AdMob
firebase_analytics for Firebase Analytics
firebase_auth for Firebase Auth
firebase_database for Firebase RTDB
firebase_storage for Firebase Cloud Storage
firebase_messaging for Firebase Messaging (FCM)
flutter_firebase_ui for quick Firebase Auth integrations (Facebook, Google, Twitter and email)
cloud_firestore for Firebase Cloud Firestore

你也可以在 Pub 上找一些第三方 Firebase 插件，它们覆盖了第一方插件没有直接覆盖的区域。

You can also find some third-party Firebase plugins on pub.dev that cover areas not directly covered by the first-party plugins.

如何构建自定义的原生集成？

How do I build my own custom native integrations?

如果有 Flutter 或它的社区插件没有的指定平台的功能，可以根据开发包与插件页面自己构建。

If there is platform-specific functionality that Flutter or its community plugins are missing, you can build your own following the developing packages and plugins page.

简单地说，Flutter 的插件架构很像在 Android 中使用事件总线：您发出一条消息，让接收方处理并向您发回一个结果。在这个例子中，接收方是运行在 Android 或 iOS 上的原生代码。

主题（样式）

Themes (Styles)

如何美化我的应用程序？

How do I theme my app?

Flutter 附带了一个内建的漂亮的 Material Design 实现，它处理了许多您通常会做的样式和主题需求

Flutter comes with a beautiful, built-in implementation of Material Design, which handles much of the styling and theming needs that you would typically do.

Xamarin.Forms 确实有一个全局的 资源字典，可以为你的应用程序共享样式。另外，预览版目前还支持主题。

Xamarin.Forms does have a global ResourceDictionary where you can share styles across your app. Alternatively, there is Theme support currently in preview.

在 Flutter 中，需要在最顶级 widget 中声明主题。

In Flutter you declare themes in the top level widget.

要在应用程序中充分利用 Material 组件，需要声明一个最顶级 widget MaterialApp 作为应用程序的入口点。 MaterialApp 是一个方便的 widget，它封装了许多实现Material Design的应用程序通常需要的各种 widget。它通过添加 Material 的指定功能来构建一个 WidgetsApp。

To take full advantage of Material Components in your app, you can declare a top level widget MaterialApp as the entry point to your application. MaterialApp is a convenience widget that wraps a number of widgets that are commonly required for applications implementing Material Design. It builds upon a WidgetsApp by adding Material-specific functionality.

还可以使用一个 WidgetApp 作为应用程序的 widget，它提供了一些相同的功能，但没有 MaterialApp 丰富。

You can also use a WidgetsApp as your app widget, which provides some of the same functionality, but is not as rich as MaterialApp.

要定制任何子组件的颜色和样式，请将主题数据（ThemeData）对象传递给MaterialApp widget。例如，在下面的代码中，主色调设置为蓝色，文本选择颜框色为红色。

To customize the colors and styles of any child components, pass a ThemeData object to the MaterialApp widget. For example, in the following code, the primary swatch is set to blue and text selection color is red.

class SampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sample App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
        textSelectionColor: Colors.red
      ),
      home: SampleAppPage(),
    );
  }
}

数据库与本地存储

Databases and local storage

如何访问共享首选项或用户默认值?

How do I access shared preferences or UserDefaults?

Xamarin.Forms 开发者可能会熟悉 Xam.Plugins.Settings 插件。

Xamarin.Forms developers will likely be familiar with the Xam.Plugins.Settings plugin.

在 Flutter 中，使用 Shared Preferences 插件就可以访问相同的功能。这个插件封装了 用户默认值 和等同 Android 的 共享首选项。

In Flutter, access equivalent functionality using the shared_preferences plugin. This plugin wraps the functionality of both UserDefaults and the Android equivalent, SharedPreferences.

在 Flutter 中如何访问 SQLite

How do I access SQLite in Flutter?

在 Xamarin.Forms 中大多数应用会使用 sqlite-net-pcl 插件来访问 SQLite 数据库。

In Xamarin.Forms most applications would use the sqlite-net-pcl plugin to access SQLite databases.

在 Flutter 中，使用 SQFlite 插件来访问这个功能。

In Flutter, access this functionality using the sqflite plugin.

调试

Debugging

应该使用什么工具调试我的 Flutter 应用？

What tools can I use to debug my app in Flutter?

请使用开发者工具 debug 你的 Flutter 和 Dart 应用。

Use the DevTools suite for debugging Flutter or Dart apps.

通知

Notifications

如何设置通知推送?

How do I set up push notifications?

在 Android 中，你可以利用 Firebase Cloud Messaging 来给应用程序设置通知推送。

In Android, you use Firebase Cloud Messaging to setup push notifications for your app.

在 Flutter 中，通过 Firebase_Messaging 插件来访问这个功能。更多关于使用 Firebase Cloud Messaging API 的信息，可以参考 firebase_messaging 插件文档。

In Flutter, access this functionality using the Firebase_Messaging plugin. For more information on using the Firebase Cloud Messaging API, see the firebase_messaging plugin documentation.

声明式 UI 介绍

为什么是声明式 UI？
Why a declarative UI?
如何在命令式框架中修改 UI
How to change UI in a declarative framework

这篇介绍描述了 Flutter 所使用的声明式 UI 和许多其他 UI 框架所使用的命令式 UI 的概念性差异

This introduction describes the conceptual difference between the declarative style used by Flutter, and the imperative style used by many other UI frameworks.

为什么是声明式 UI？

Why a declarative UI?

从 Win32 到 Web 再到 Android 和 iOS，框架通常使用一种命令式的编程风格来完成 UI 编程。这可能是你最熟悉的风格 — 你手动构建一个全功能的 UI 实例，比如一个 UIView 或其他类似的，在随后 UI 发生变化时，使用方法或 Setter 修改它。

Frameworks from Win32 to web to Android and iOS typically use an imperative style of UI programming. This might be the style you’re most familiar with—where you manually construct a full-functioned UI entity, such as a UIView or equivalent, and later mutate it using methods and setters when the UI changes.

为了减轻开发人员的负担，无需编写如何在不同的 UI 状态之间进行切换的代码， Flutter 相反，让开发人员描述当前的 UI 状态，并将转换交给框架。

In order to lighten the burden on developers from having to program how to transition between various UI states, Flutter, by contrast, lets the developer describe the current UI state and leaves the transitioning to the framework.

然而，这需要稍微改变下如何操作 UI 的思考方式

This, however, requires a slight shift in thinking for how to manipulate UI.

如何在命令式框架中修改 UI

How to change UI in a declarative framework

思考像下面这样一个简单的例子:

Consider a simplified example below:

View B (contained by view A) morphs from containing two views, c1 and c2, to containing only view c3

在命令式风格中，你通常需要使用选择器 findViewById 或类似函数获取到 ViewB 的实例 b 和所有权，并调用相关的修改的方法（并隐式的使其失效）。例如：

In the imperative style, you would typically go to ViewB’s owner and retrieve the instance b using selectors or with findViewById or similar, and invoke mutations on it (and implicitly invalidate it). For example:

// Imperative style
b.setColor(red)
b.clearChildren()
ViewC c3 = new ViewC(...)
b.add(c3)

由于 UI 真实的来源可能比实例 b 本身的存活周期更长，你可能还需要在 ViewB 的构造函数中复制此配置。

You might also need to replicate this configuration in the constructor of ViewB since the source of truth for the UI might outlive instance b itself.

在声明式风格中，视图配置（如 Flutter 的 Widget ）是不可变的，它只是轻量的“蓝图”。要改变 UI，widget 会在自身上触发重建（在 Flutter 中最常见的方法是在 StatefulWidgets 组件上调用 setState()）并构造一个新的 Widget 子树。

In the declarative style, view configurations (such as Flutter’s Widgets) are immutable and are only lightweight “blueprints”. To change the UI, a widget triggers a rebuild on itself (most commonly by calling setState() on StatefulWidgets in Flutter) and constructs a new Widget subtree.

// Declarative style
return ViewB(
  color: red,
  child: ViewC(...),
)

在这里，当用户界面发生变化时，Flutter 不会修改旧的实例 b，而是构造新的 widget 实例。框架使用 RenderObjects 管理传统 UI 对象的职责（比如维护布局的状态）。 RenderObjects 在帧之间保持不变， Flutter 的轻量级 widget 通知框架在状态之间修改 RenderObjects， Flutter 框架则处理其余部分。

Here, rather than mutating an old instance b when the UI changes, Flutter constructs new Widget instances. The framework manages many of the responsibilities of a traditional UI object (such as maintaining the state of the layout) behind the scenes with RenderObjects. RenderObjects persist between frames and Flutter’s lightweight Widgets tell the framework to mutate the RenderObjects between states. The Flutter framework handles the rest.

Building a web application with Flutter

Requirements
Create a new project with web support
- Set up
- Create and run
  - IDE
  - Command line
- Build
Add web support to an existing app

This page covers the following steps for getting started with web support:

Configure the flutter tool for web support.
Create a new project with web support.
Run a new project with web support.
Build an app with web support.
Add web support to an existing project.

Requirements

To create a Flutter app with web support, you need the following software:

Flutter SDK. See the Flutter SDK installation instructions.
Chrome; debugging a web app requires the Chrome browser.
Optional: An IDE that supports Flutter. You can install Android Studio, IntelliJ IDEA, or Visual Studio Code and install the Flutter and Dart plugins to enable language support and tools for refactoring, running, debugging, and reloading your web app within an editor. See setting up an editor for more details.

For more information, see the web FAQ.

Create a new project with web support

You can use the following steps to create a new project with web support.

Set up

Run the following commands to use the latest version of the Flutter SDK:

$ flutter channel stable
$ flutter upgrade

If Chrome is installed, the flutter devices command outputs a Chrome device that opens the Chrome browser with your app running, and a Web Server that provides the URL serving the app.

$ flutter devices
1 connected device:

Chrome (web) • chrome • web-javascript • Google Chrome 88.0.4324.150

In your IDE, you should see Chrome (web) in the device pulldown.

Create and run

Creating a new project with web support is no different than creating a new Flutter project for other platforms.

IDE

Create a new app in your IDE and it automatically creates iOS, Android, and web versions of your app. (And macOS, too, if you’ve enabled desktop support.) From the device pulldown, select Chrome (web) and run your app to see it launch in Chrome.

Command line

To create a new app that includes web support (in addition to mobile support), run the following commands, substituting myapp with the name of your project:

$ flutter create myapp
$ cd myapp

To serve your app from localhost in Chrome, enter the following from the top of the package:

$ flutter run -d chrome

The flutter run command launches the application using the development compiler in a Chrome browser.

Build

Run the following command to generate a release build:

$ flutter build web

A release build uses dart2js (instead of the development compiler) to produce a single JavaScript file main.dart.js. You can create a release build using release mode (flutter run --release) or by using flutter build web. This populates a build/web directory with built files, including an assets directory, which need to be served together.

You can also include --web-renderer html or --web-renderer canvaskit to select between the HTML or CanvasKit renderers, respectively. For more information, see Web renderers.

For more information, see Build and release a web app.

Add web support to an existing app

To add web support to an existing project created using a previous version of Flutter, run the following command from your project’s directory:

$ flutter create .

实用教程

Animation
Design
Effects
Forms
Gestures
Images
Lists
Maintenance
Navigation
Networking
Persistence
Plugins
Testing
- Integration
- Unit
- Widget

本节内容包含了一个又一个的实用教程，帮助你解决编写 Flutter 应用中的常见问题。

This cookbook contains recipes that demonstrate how to solve common problems while writing Flutter apps. Each recipe is self-contained and can be used as a reference to help you build up an application.

Animation

Design

Effects

Forms

Gestures

Images

Lists

Maintenance

把报错信息通过服务上传

Networking

Persistence

Plugins

Testing

Integration

Unit

如果想看到更多的教程，可以参考我们的社区中文教程页面。

Codelabs & workshops

适用于初级开发者
Good for beginners
下一步
Next steps
使用 Flutter 设计 UI
Designing a Flutter UI
在 Flutter 应用中集成
Using Flutter with…
测试
Testing
撰写平台特别的代码
Writing platform-specific code
其他资源
Other resources

Flutter 的 codelabs 是一份为新手准备的入门指南。一些 codelabs 运行在 DartPad—上，这意味着你不需要下载任何东西就能够轻松学习。

Flutter workshops 与 codelabs 类似，但由讲师指导并始终使用 DartPad。 workshop 链接也会提供给你相关的 YouTube 视频，该视频会告诉你在哪里可以找到相关的 DartPad 链接。

The Flutter codelabs provide a guided, hands-on coding experience. Some codelabs run in DartPad—no downloads required!

Flutter workshops are similar to the codelabs, but are instructor led and always use DartPad. The provided workshop link takes you to the relevant YouTube video, which tells you where to find the associated DartPad link.

适用于初级开发者

Good for beginners

如果你刚开始学习 Flutter，我们推荐你学习下面的 Codelab 之一：

If you’re new to Flutter, we recommend starting with one of these codelabs:

构建你的第一个 Flutter App (workshop) 新!
我们非常受欢迎的「编写你的第一个 Flutter App，第一部分」 codelab（如下所列）的讲师指导版。
Building your first Flutter app (workshop) NEW!
An instructor-led version of our very popular “Write your first Flutter app, part 1” codelab (listed below).
编写你的第一个 Flutter App，第一部分
你将完成一个简单的移动应用程序，它将具有为一个创业公司生成建议的公司名称的功能。在本节中，你将使用一个 package 并使用它生成的随机文字对创建一个无限滚动的列表。你也可以在文档网站的 codelab 页面中找到它。
Write your first Flutter app, part 1
Create a simple mobile app that generates proposed names for a startup company. In part one, you’ll use a package that returns pairs of words at random and inserts them into an infinite scrolling list. You can also find this codelab on docs.flutter.dev.
编写你的第一个 Flutter App，第二部分
你将完成一个简单的移动应用程序，功能是：为一个创业公司生成建议的公司名称（第二部分）。在本节，你将在一个基础的 Flutter 应用里加入交互功能，同时创建第二个页面（Flutter 里称之为 route）用户可以进入这个页面。最终，你将可以修改应用的主题（配色）。
Write your first Flutter app, part 2
Create a simple mobile app that generates proposed names for a startup company. In part two, you’ll extend the example from part 1 to allow the user to select favorite word pairs, and add a second “Saved Favorites” page where users can view the selected names. Finally, you’ll change the app’s theme color.
编写你的第一个 Flutter web 应用
在 DartPad 中实现一个简单的 web 应用（无需下载任何东西！），它将会展示一个具有三个文本输入框的注册界面。当用户填完输入框，一个进度条动画将会展示在登陆区域的顶部。这篇 codelab 是为 web 量身定做的，但如果你下载并配置好了 Android 以及 iOS 的工具，那么整个应用同样也能运行在 Android 以及 iOS 的设备上。
Write your first Flutter app on the web
Implement a simple web app in DartPad (no downloads required!) that displays a sign-in screen containing three text fields. As the user fills out the fields, a progress bar animates along the top of the sign-in area. This codelab is written specifically for the web, but if you have downloaded and configured Android and iOS tooling, the completed app works on Android and iOS devices, as well.
使用 Flutter 创建精美的 UI
这将是一次“深入探索”，而不是 Flutter 的“入门级教程”。在本篇 codelab 中，你将会编写一个聊天应用，其中将包括简单的动画，以及在 iOS 和 Android 上自定义 UI 等内容。
Building beautiful UIs with Flutter
A deeper “first dive” than “Write your first Flutter app.” Create a chat app that includes a simple animation, and customizes the UI for iOS and Android. As part of this codelab, learn how to use keyboard shortcuts in Android Studio.

下一步

Next steps

在 Flutter 中构建滚动体验 (workshop) 新!
从一个执行简单、直接滚动的应用程序入门，并通过使用 sliver 增强它以创建奇特的自定义滚动效果。
Building scrolling experiences in Flutter (workshop) NEW!
Start with an app that performs simple, straightforward scrolling and enhance it to create fancy and custom scrolling effects by using slivers.
Dart 空安全实战 (workshop) 新!
基于 dart.cn 站点上的空安全 codelab 的讲师指导版 workshop。
Dart null safety in Action (workshop) NEW!
An instructor-led workshop based on the Null safety codelab on the dart.dev site.
如何使用 inherited widgets 管理应用程序状态 (workshop) 新!
了解如何使用 InheritedWidget 类（Flutter 提供的基础状态管理方案之一）管理应用数据的状态。
How to manage application states using inherited widgets (workshop) NEW!
Learn how to manage the state of your app’s data by using the InheritedWidget class, one of the low-level state management classes provided by Flutter.

使用 Flutter 设计 UI

Designing a Flutter UI

了解 Material Design 和 Flutter基本概念，例如布局和动画：

Learn about Material Design and basic Flutter concepts, like layout and animations:

Flutter 布局基础要点
在网页浏览器里使用 DartPad 学习基础的 Flutter 布局知识。
Basic Flutter layout concepts
Use DartPad in a browser (no downloads required!) to learn the basics of creating a Flutter layout.
如何使用 Flutter Inspector 调试布局
(非官方产出的 codelab) 手把手的介绍如何使用 Flutter Inspector 和 Layout Explorer 调试一些常见的布局问题。
How to debug layout issues with the Flutter Inspector
Not an official codelab, but step-by-step instructions on how to debug common layout problems using the Flutter Inspector and Layout Explorer.
渐变动画
使用 DartPad 学习如果创建渐变动画。
Implicit animations
Use DartPad (no downloads required!) to learn how to use implicit animations to add motion and create visual effects for the widgets in your UI.
使用 Material Motion 为 Flutter 构建精美的过渡动画
了解如何使用 Material animations package 为名叫 Reply 的 Material 应用添加预构建的过渡。
Building Beautiful Transitions with Material Motion for Flutter
Learn how to use the Material animations package to add pre-built transitions to a Material app called Reply.
MDC Flutter 教程 1：Material 组件基础
学习使用 Material 核心组件构建一个简单的应用。我们最终会构建一个售卖衣服和家居的电子商务应用－ Shrine，本节将从一个简单的登陆页面开始帮助你在 Flutter 上使用 Material 组件。
MDC-101 Flutter: Material Components (MDC) Basics
Learn the basics of using Material Components by building a simple app with core components. The four MDC codelabs guide you through building an e-commerce app called Shrine. You’ll start by building a login page using several of MDC Flutter’s components.
MDC Flutter 教程 2：Material 组件结构和布局
学习如何在 Flutter 中使用 Material 样式的结构和布局。通过添加导航、结构和数据，继续构建那个电子商务应用－ Shrine。
MDC-102 Flutter: Material Structure and Layout
Learn how to use Material for structure and layout in Flutter. Continue building the e-commerce app, introduced in MDC-101, by adding navigation, structure, and data.
MDC Flutter 教程 3：Material 组件主题、形状、阴影和类型
探寻如何通过 Flutter Material 组件让你的产品更出众，并通过你的设计传达产品的品牌。我们会为我们的电子商务应用加入一个首页展现所有的产品。
MDC-103 Flutter: Material Theming with Color, Shape, Elevation, and Type
Discover how Material Components for Flutter make it easy to differentiate your product, and express your brand through design. Continue building your e-commerce app by adding a home screen that displays products.
MDC Flutter 教程 4：Material 组件进阶
改进设计并学习如何使用高级的组件 - backdrop 菜单。本期我们将通过加入一个全屏（backdrop）样式的菜单，用于分类显示你的产品。至此我们就结束了这个电子商务应用的构建
MDC-104 Flutter: Material Advanced Components
Improve your design and learn to use our advanced component backdrop menu. Finish your e-commerce app by adding a backdrop with a menu that filters products by the selected category.

在 Flutter 应用中集成

Using Flutter with…

学习如何使用在 Flutter 中使用其他技术产品/平台：

Learn how to use Flutter with other technologies.

在 Flutter 应用中添加谷歌地图
在应用里显示谷歌地图，接收网络传回的数据，在地图上显示一个标示。
Adding Google Maps to a Flutter app
Display a Google map in an app, retrieve data from a web service, and display the data as markers on the map.
为 Flutter 应用加入 AdMob
为一个名叫 Awesome Drawing Quiz 的小游戏加入 AdMob 标语广告、插页式广告和奖励广告。这是一个看图猜字的游戏。
Adding AdMob Ads to a Flutter app
Learn how to add an AdMob banner, an interstitial ad, and a rewarded ad to an app called Awesome Drawing Quiz, a game that lets players guess the name of the drawing.
向 Flutter 应用中添加 AdMob 广告横幅以及原生嵌入式广告
学习如何在一个旅行预约应用中嵌入 inline banner 以及原生广告。
Adding an AdMob banner and native inline ads to a Flutter app
Learn how to implement inline banner and native ads to a travel booking app that lists possible flight destinations.
为 Flutter 应用添加应用内购买功能
扩展一个使用 Dash 吉祥物作为货币的简单游戏应用程序，以提供三种类型的应用程序内购买：消耗品、非消耗品和订阅。
Adding in-app purchases to your Flutter app
Extend a simple gaming app that uses the Dash mascot as currency to offer three types of in-app purchases: consumable, non-consumable, and subscription.
使用 Google 相册和 Flutter 构建照片共享应用
构建一个实地考察应用程序，允许你和旅行中的其他成员分享照片。
Build a Photo Sharing app with Google Photos and Flutter
Build a field trip app that allows you and other members of the trip to share photos.
使用 Dialogflow 和 Flutter 为移动设备构建语音机器人 (workshop) 新!
Dialogflow 和 Flutter codelab 的讲师指导版本（如下所列）。
Build voice bots for mobile with Dialogflow and Flutter (workshop) NEW!
An instructor-led version of the Dialogflow and Flutter codelab (listed below).
使用 Dialogflow 和 Flutter 为 Android 构建语音机器人
学习如何构建可以回答有关 Dialogflow 工具的最常见问题的移动式常见问题解答机器人。终端用户可以通过移动设备的内置麦克风与文本界面交互或流式传输语音交互。
Build voice bots for Android with Dialogflow and Flutter
Learn how to build a mobile FAQ bot that can answer most common questions about the tool Dialogflow. End users can interact with the text interface or stream a voice interaction via the built-in microphone of a mobile device.
在 Flutter 里使用 Firebase (workshop) 新!
我们广受欢迎的「在 Flutter 里使用 Firebase」codelab 的讲师指导版本（如下所列）。
Get to know Firebase for Flutter (workshop) NEW!
An instructor-led version of our popular “Get to know Firebase for Flutter” codelab (listed below).
在 Flutter 里使用 Firebase
学习如何在 Flutter 里使用 Firebase 实时数据库的功能，以及如何使用事物 (transaction) 同时更新不同设备里的信息。
Get to know Firebase for Flutter
Build an event RSVP and guestbook chat app on both Android and iOS using Flutter, authenticating users with Firebase Authentication and sync data using Cloud Firestore.
使用 Cloud Firestore 和 Flutter 构建一个多平台应用
构建一个多平台的餐馆推荐应用，只需要一套 Dart 代码，就可以运行在 Android、iOS 和 Web 平台。
Multi-platform Firestore Flutter
Build a multi-platform restaurant recommendation app powered by Flutter and Cloud Firestore. The finished app runs on Android, iOS, and web, from a single Dart codebase.

测试

Testing

学习如何测试你的 Flutter 应用：

Learn how to test your Flutter application.

如何测试一个 Flutter 应用
从一个简单的应用开始，该应用使用 Provider package 来管理状态，进而对提供应用进行单元测试 —— 为其中两个小部件编写小部件测试；使用 Flutter Driver 创建集成测试。
How to test a Flutter app
Start with a simple app that manages state with the Provider package. Unit test the provider package. Write widget tests for two of the widgets. Use Flutter Driver to create an integration test.

撰写平台特别的代码

Writing platform-specific code

学习如何撰写在特定的平台运行的代码，比如 iOS、Android、Web 和桌面端。

Learn how to write code that’s targeted for specific platforms, like iOS, Android, the web, and the desktop.

使用 Flutter 构建 iOS 风格的应用构建 iOS 风格和体验的购物应用 Shrine，创建多个选项卡，使用 provider package 来管理不同的页面。
Building a Cupertino app with Flutter
Build a version of the Shrine shopping app (used in the Material Design codelabs) using the Cupertino package to create an iOS style look and feel. Create multiple tabs and navigate between them. Use the provider package to manage state between screens.
如何编写一个 Flutter（原生平台）插件
编写一个原生平台（iOS 和 Android）的音乐插件，处理原生平台音频，然后构建一个示例应用，使用这个插件制作一个音乐键盘。
How to write a Flutter plugin
Learn how to write a plugin by creating a music plugin for iOS and Android that processes audio on the host platform. Then make an example app that uses your plugin to make a music keyboard.
在 Flutter Web 应用使用插件
构建一个完整的应用来显示 GitHub 仓库的星星（收藏）数量，使用 Dart DevTools 开发者工具进行一些简答的调试，然后将应用部署到 Firebase 上。最后使用 Flutter 插件启动应用以及显示隐私权政策。
Using a plugin with a Flutter web app
Finish an app that reports the number of stars on a GitHub repository. use Dart DevTools to do some simple debugging, and Host your app on Firebase and, finally, use a Flutter plugin to launch the app and open the hosted privacy policy.
编写一个 Flutter 桌面应用
构建一个 Flutter 桌面应用以通过 GitHub APIs 来检索你的代码仓库 (repo)，已分配的问题 (issue) 和拉取请求 (pull request)。本任务还有一部分内容，需要创建并使用插件，让原生 API 和桌面应用进行交互，并为 GitHub APIs 构建一个类型安全的客户端库。
Write a Flutter desktop application
Build a Flutter desktop app that accesses GitHub APIs to retrieve your repositories, assigned issues, and pull requests. As part of this task, create and use plugins to interact with native APIs and desktop applications, and use code generation to build type-safe client libraries for GitHub’s APIs.

其他资源

Other resources

查看更多 Dart 相关的 codelab，请在 Dart 网站上查看 codelabs 页面。

下面这些线上的课程也很不错：

For Dart-specific codelabs, see the codelabs page on the Dart site.

We also recommend the following online class:

使用 Dart 完整开发 Flutter 应用
The Complete Flutter Development Bootcamp Using Dart

Flutter 实践教程

Flutter 实践教程，帮助你完成相对较为完整的 Flutter 小应用。

The Flutter tutorials teach you how to use the Flutter framework to build mobile applications for iOS and Android.

你可以选择以下教程：

Choose from the following:

Flutter 布局构建教程
使用 Flutter 构建基础的布局，领会基本布局机制。你可以通过截图示例构建应用的布局结构。
Building layouts
How to build layouts using Flutter’s layout mechanism. Once you’ve learned basic principles, you’ll build the layout for a sample screenshot.
为你的 Flutter 应用加入交互体验
你将为上一个教程中构建的应用加入新的功能，让一个图标变得可点击。也包含有 widgets state 管理的不同方式。
Adding interactivity to your Flutter app
You’ll extend the simple layout app created in “Building Layouts in Flutter” to make an icon tappable. Different ways of managing a widget’s state are also discussed.
在 Flutter 应用里实现动画效果
了解和使用 Flutter 动画的基础类 (controllers, Animatable, curves, listeners, builders)，通过几个不同角度帮助你了解 Flutter 的动画 API。
Animations in Flutter
Explains the fundamental classes in the Flutter animation package (controllers, Animatable, curves, listeners, builders), as it guides you through a progression of tween animations using different aspects of the animation APIs.
Flutter 应用里的国际化
了解 Flutter 应用里的国际化，依照用户自己的语言和格式约定显示内容。
Internationalizing Flutter apps
Learn how to internationalize your Flutter application. A guide through the widgets and classes that enable apps to display their content using the user’s language and formatting conventions.

Widgets 介绍

Flutter 从 React 中吸取灵感，通过现代化框架创建出精美的组件。它的核心思想是用 widget 来构建你的 UI 界面。 Widget 描述了在当前的配置和状态下视图所应该呈现的样子。当 widget 的状态改变时，它会重新构建其描述（展示的 UI），框架则会对比前后变化的不同，以确定底层渲染树从一个状态转换到下一个状态所需的最小更改。

Flutter widgets are built using a modern framework that takes inspiration from React. The central idea is that you build your UI out of widgets. Widgets describe what their view should look like given their current configuration and state. When a widget’s state changes, the widget rebuilds its description, which the framework diffs against the previous description in order to determine the minimal changes needed in the underlying render tree to transition from one state to the next.

Hello world

创建一个最小的 Flutter 应用简单到仅需调用 runApp() 方法并传入一个 widget 即可：

The minimal Flutter app simply calls the runApp() function with a widget:

import 'package:flutter/material.dart';

void main() {
  runApp(
    const Center(
      child: Text(
        'Hello, world!',
        textDirection: TextDirection.ltr,
      ),
    ),
  );
}

runApp() 函数会持有传入的 Widget，并且使它成为 widget 树中的根节点。在这个例子中，Widget 树有两个 widgets， Center widget 及其子 widget —— Text widget。框架会强制让根 widget 铺满整个屏幕，也就是说“Hello World”会在屏幕上居中显示。在这个例子我们需要指定文字的方向，当使用 MaterialApp widget 时，你就无需考虑这一点，之后我们会进一步的描述。

The runApp() function takes the given Widget and makes it the root of the widget tree. In this example, the widget tree consists of two widgets, the Center widget and its child, the Text widget. The framework forces the root widget to cover the screen, which means the text “Hello, world” ends up centered on screen. The text direction needs to be specified in this instance; when the MaterialApp widget is used, this is taken care of for you, as demonstrated later.

在写应用的过程中，取决于是否需要管理状态，你通常会创建一个新的组件继承 StatelessWidget 或 StatefulWidget。 Widget 的主要工作是实现 build() 方法，该方法根据其它较低级别的 widget 来描述这个 widget。框架会逐一构建这些 widget，直到最底层的描述 widget 几何形状的 RenderObject。

When writing an app, you’ll commonly author new widgets that are subclasses of either StatelessWidget or StatefulWidget, depending on whether your widget manages any state. A widget’s main job is to implement a build() function, which describes the widget in terms of other, lower-level widgets. The framework builds those widgets in turn until the process bottoms out in widgets that represent the underlying RenderObject, which computes and describes the geometry of the widget.

基础 widgets

Basic widgets

Flutter 自带了一套强大的基础 widgets，下面列出了一些常用的：

Flutter comes with a suite of powerful basic widgets, of which the following are commonly used:

Text
Text widget 可以用来在应用内创建带样式的文本。

Text
The Text widget lets you create a run of styled text within your application.

Row, Column
这两个 flex widgets 可以让你在水平 (Row) 和垂直(Column) 方向创建灵活的布局。它是基于 web 的 flexbox 布局模型设计的。

Row, Column
These flex widgets let you create flexible layouts in both the horizontal (Row) and vertical (Column) directions. The design of these objects is based on the web’s flexbox layout model.

Stack
Stack widget 不是线性（水平或垂直）定位的，而是按照绘制顺序将 widget 堆叠在一起。你可以用 Positioned widget 作为Stack 的子 widget，以相对于 Stack 的上，右，下，左来定位它们。 Stack 是基于 Web 中的绝对位置布局模型设计的。

Stack
Instead of being linearly oriented (either horizontally or vertically), a Stack widget lets you place widgets on top of each other in paint order. You can then use the Positioned widget on children of a Stack to position them relative to the top, right, bottom, or left edge of the stack. Stacks are based on the web’s absolute positioning layout model.

Container
Container widget 可以用来创建一个可见的矩形元素。 Container 可以使用 BoxDecoration 来进行装饰，如背景，边框，或阴影等。 Container 还可以设置外边距、内边距和尺寸的约束条件等。另外，Container可以使用矩阵在三维空间进行转换。

Container
The Container widget lets you create a rectangular visual element. A container can be decorated with a BoxDecoration, such as a background, a border, or a shadow. A Container can also have margins, padding, and constraints applied to its size. In addition, a Container can be transformed in three dimensional space using a matrix.

下面是一些简单的 widget，它们结合了上面提到的 widget 和一些其他的 widget：

Below are some simple widgets that combine these and other widgets:

import 'package:flutter/material.dart';

class MyAppBar extends StatelessWidget {
  const MyAppBar({required this.title, Key? key}) : super(key: key);

  // Fields in a Widget subclass are always marked "final".

  final Widget title;

  @override
  Widget build(BuildContext context) {
    return Container(
      height: 56.0, // in logical pixels
      padding: const EdgeInsets.symmetric(horizontal: 8.0),
      decoration: BoxDecoration(color: Colors.blue[500]),
      // Row is a horizontal, linear layout.
      child: Row(
        // <Widget> is the type of items in the list.
        children: [
          const IconButton(
            icon: Icon(Icons.menu),
            tooltip: 'Navigation menu',
            onPressed: null, // null disables the button
          ),
          // Expanded expands its child
          // to fill the available space.
          Expanded(
            child: title,
          ),
          const IconButton(
            icon: Icon(Icons.search),
            tooltip: 'Search',
            onPressed: null,
          ),
        ],
      ),
    );
  }
}

class MyScaffold extends StatelessWidget {
  const MyScaffold({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Material is a conceptual piece
    // of paper on which the UI appears.
    return Material(
      // Column is a vertical, linear layout.
      child: Column(
        children: [
          MyAppBar(
            title: Text(
              'Example title',
              style: Theme.of(context) //
                  .primaryTextTheme
                  .headline6,
            ),
          ),
          const Expanded(
            child: Center(
              child: Text('Hello, world!'),
            ),
          ),
        ],
      ),
    );
  }
}

void main() {
  runApp(
    const MaterialApp(
      title: 'My app', // used by the OS task switcher
      home: SafeArea(
        child: MyScaffold(),
      ),
    ),
  );
}

请确认在 pubspec.yaml 文件中 flutter 部分有 uses-material-design: true 这条，它能让你使用预置的 Material icons。

Be sure to have a uses-material-design: true entry in the flutter section of your pubspec.yaml file. It allows you to use the predefined set of Material icons. It’s generally a good idea to include this line if you are using the Materials library.

name: my_app
flutter:
  uses-material-design: true

为了获得(MaterialApp)主题的数据，许多 Material Design 的 widget 需要在 MaterialApp 中才能显现正常。因此，请使用 MaterialApp 运行应用。

Many Material Design widgets need to be inside of a MaterialApp to display properly, in order to inherit theme data. Therefore, run the application with a MaterialApp.

MyAppBar widget 创建了一个高 56 独立像素，左右内边距 8 像素的 Container。在容器内，MyAppBar 以 Row 布局来组织它的子元素。中间的子 widget（title widget），被标记为 Expanded，这意味着它会扩展以填充其它子 widget 未使用的可用空间。你可以定义多个Expanded 子 widget，并使用 flex 参数确定它们占用可用空间的比例。

The MyAppBar widget creates a Container with a height of 56 device-independent pixels with an internal padding of 8 pixels, both on the left and the right. Inside the container, MyAppBar uses a Row layout to organize its children. The middle child, the title widget, is marked as Expanded, which means it expands to fill any remaining available space that hasn’t been consumed by the other children. You can have multiple Expanded children and determine the ratio in which they consume the available space using the flex argument to Expanded.

MyScaffold widget 将其子 widget 组织在垂直列中。在列的顶部，它放置一个 MyAppBar 实例，并把 Text widget 传给它来作为应用的标题。把 widget 作为参数传递给其他 widget 是一个很强大的技术，它可以让你以各种方式创建一些可重用的通用组件。最后，MyScaffold 使用 Expanded 来填充剩余空间，其中包含一个居中的消息。

The MyScaffold widget organizes its children in a vertical column. At the top of the column it places an instance of MyAppBar, passing the app bar a Text widget to use as its title. Passing widgets as arguments to other widgets is a powerful technique that lets you create generic widgets that can be reused in a wide variety of ways. Finally, MyScaffold uses an Expanded to fill the remaining space with its body, which consists of a centered message.

有关更多信息，请参阅布局。

For more information, see Layouts.

使用 Material 组件

Using Material Components

Flutter 提供了许多 widget，可帮助你构建遵循 Material Design 的应用。 Material 应用以 MaterialApp widget 开始，它在你的应用的底层下构建了许多有用的 widget。这其中包括 Navigator，它管理由字符串标识的 widget 栈，也称为“routes”。 Navigator 可以让你在应用的页面中平滑的切换。使用 MaterialApp widget 不是必须的，但这是一个很好的做法。

Flutter provides a number of widgets that help you build apps that follow Material Design. A Material app starts with the MaterialApp widget, which builds a number of useful widgets at the root of your app, including a Navigator, which manages a stack of widgets identified by strings, also known as “routes”. The Navigator lets you transition smoothly between screens of your application. Using the MaterialApp widget is entirely optional but a good practice.

import 'package:flutter/material.dart';

void main() {
  runApp(
    const MaterialApp(
      title: 'Flutter Tutorial',
      home: TutorialHome(),
    ),
  );
}

class TutorialHome extends StatelessWidget {
  const TutorialHome({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Scaffold is a layout for
    // the major Material Components.
    return Scaffold(
      appBar: AppBar(
        leading: const IconButton(
          icon: Icon(Icons.menu),
          tooltip: 'Navigation menu',
          onPressed: null,
        ),
        title: const Text('Example title'),
        actions: const [
          IconButton(
            icon: Icon(Icons.search),
            tooltip: 'Search',
            onPressed: null,
          ),
        ],
      ),
      // body is the majority of the screen.
      body: const Center(
        child: Text('Hello, world!'),
      ),
      floatingActionButton: const FloatingActionButton(
        tooltip: 'Add', // used by assistive technologies
        child: Icon(Icons.add),
        onPressed: null,
      ),
    );
  }
}

现在我们已经从 MyAppBar 和 MyScaffold 切换到了 material.dart 中的 AppBar 和 Scaffold widget，我们的应用更“Material”了一些。例如，标题栏有了阴影，标题文本会自动继承正确的样式，此外还添加了一个浮动操作按钮。

Now that the code has switched from MyAppBar and MyScaffold to the AppBar and Scaffold widgets, and from material.dart, the app is starting to look a bit more Material. For example, the app bar has a shadow and the title text inherits the correct styling automatically. A floating action button is also added.

注意，widget 作为参数传递给了另外的 widget。 Scaffold widget 将许多不同的 widget 作为命名参数，每个 widget 都放在了 Scofford 布局中的合适位置。同样的，AppBar widget 允许我们给 leading、title widget 的 actions 传递 widget。这种模式在整个框架会中重复出现，在设计自己的 widget 时可以考虑这种模式。

Notice that widgets are passed as arguments to other widgets. The Scaffold widget takes a number of different widgets as named arguments, each of which are placed in the Scaffold layout in the appropriate place. Similarly, the AppBar widget lets you pass in widgets for the leading widget, and the actions of the title widget. This pattern recurs throughout the framework and is something you might consider when designing your own widgets.

有关更多信息，请参阅 Material 组件。

For more information, see Material Components widgets.

处理手势

Handling gestures

大多数应用都需要通过系统来处理一些用户交互。构建交互式应用程序的第一步是检测输入手势，这里通过创建一个简单的按钮来了解其工作原理：

Most applications include some form of user interaction with the system. The first step in building an interactive application is to detect input gestures. See how that works by creating a simple button:

import 'package:flutter/material.dart';

class MyButton extends StatelessWidget {
  const MyButton({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () {
        print('MyButton was tapped!');
      },
      child: Container(
        height: 50.0,
        padding: const EdgeInsets.all(8.0),
        margin: const EdgeInsets.symmetric(horizontal: 8.0),
        decoration: BoxDecoration(
          borderRadius: BorderRadius.circular(5.0),
          color: Colors.lightGreen[500],
        ),
        child: const Center(
          child: Text('Engage'),
        ),
      ),
    );
  }
}

void main() {
  runApp(
    const MaterialApp(
      home: Scaffold(
        body: Center(
          child: MyButton(),
        ),
      ),
    ),
  );
}

GestureDetector widget 没有可视化的展现，但它能识别用户的手势。当用户点击 Container 时， GestureDetector 会调用其 onTap() 回调，在这里会向控制台打印一条消息。你可以使用 GestureDetector 检测各种输入的手势，包括点击，拖动和缩放。

The GestureDetector widget doesn’t have a visual representation but instead detects gestures made by the user. When the user taps the Container, the GestureDetector calls its onTap() callback, in this case printing a message to the console. You can use GestureDetector to detect a variety of input gestures, including taps, drags, and scales.

许多 widget 使用 GestureDetector 为其他 widget 提供可选的回调。例如，IconButton、ElevatedButton 和 FloatingActionButton widget 都有 onPressed() 回调，当用户点击 widget 时就会触发这些回调。

Many widgets use a GestureDetector to provide optional callbacks for other widgets. For example, the IconButton, ElevatedButton, and FloatingActionButton widgets have onPressed() callbacks that are triggered when the user taps the widget.

有关更多信息，请参阅 Flutter 中的手势。

For more information, see Gestures in Flutter.

根据用户输入改变 widget

Changing widgets in response to input

到目前为止，这个页面仅使用了无状态的 widget。无状态 widget 接收的参数来自于它的父 widget，它们储存在 final 成员变量中。当 widget 需要被 build() 时，就是用这些存储的变量为创建的 widget 生成新的参数。

So far, this page has used only stateless widgets. Stateless widgets receive arguments from their parent widget, which they store in final member variables. When a widget is asked to build(), it uses these stored values to derive new arguments for the widgets it creates.

为了构建更复杂的体验，例如，以更有趣的方式对用户输入做出反应—应用通常带有一些状态。 Flutter 使用 StatefulWidgets 来实现这一想法。 StatefulWidgets 是一种特殊的 widget，它会生成 State 对象，用于保存状态。看看这个基本的例子，它使用了前面提到的 ElevatedButton：

In order to build more complex experiences—for example, to react in more interesting ways to user input—applications typically carry some state. Flutter uses StatefulWidgets to capture this idea. StatefulWidgets are special widgets that know how to generate State objects, which are then used to hold state. Consider this basic example, using the ElevatedButton mentioned earlier:

import 'package:flutter/material.dart';

class Counter extends StatefulWidget {
  // This class is the configuration for the state.
  // It holds the values (in this case nothing) provided
  // by the parent and used by the build  method of the
  // State. Fields in a Widget subclass are always marked
  // "final".

  const Counter({Key? key}) : super(key: key);

  @override
  _CounterState createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  int _counter = 0;

  void _increment() {
    setState(() {
      // This call to setState tells the Flutter framework
      // that something has changed in this State, which
      // causes it to rerun the build method below so that
      // the display can reflect the updated values. If you
      // change _counter without calling setState(), then
      // the build method won't be called again, and so
      // nothing would appear to happen.
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    // This method is rerun every time setState is called,
    // for instance, as done by the _increment method above.
    // The Flutter framework has been optimized to make
    // rerunning build methods fast, so that you can just
    // rebuild anything that needs updating rather than
    // having to individually changes instances of widgets.
    return Row(
      mainAxisAlignment: MainAxisAlignment.center,
      children: <Widget>[
        ElevatedButton(
          onPressed: _increment,
          child: const Text('Increment'),
        ),
        const SizedBox(width: 16),
        Text('Count: $_counter'),
      ],
    );
  }
}

void main() {
  runApp(
    const MaterialApp(
      home: Scaffold(
        body: Center(
          child: Counter(),
        ),
      ),
    ),
  );
}

您可能想知道为什么 StatefulWidget 和 State 是独立的对象。在 Flutter 中，这两种类型的对象具有不同的生命周期。 Widget 是临时对象，用于构造应用当前状态的展示。而 State 对象在调用 build() 之间是持久的，以此来存储信息。

You might wonder why StatefulWidget and State are separate objects. In Flutter, these two types of objects have different life cycles. Widgets are temporary objects, used to construct a presentation of the application in its current state. State objects, on the other hand, are persistent between calls to build(), allowing them to remember information.

上面的示例接受用户输入并直接在其 build() 方法中直接使用结果。在更复杂的应用中，widget 层次不同的部分可能负责不同的关注点；例如，一个 widget 可能呈现复杂的用户界面，来收集像日期或位置这样特定的信息，而另一个 widget 可能使用该信息来改变整体的展现。

The example above accepts user input and directly uses the result in its build() method. In more complex applications, different parts of the widget hierarchy might be responsible for different concerns; for example, one widget might present a complex user interface with the goal of gathering specific information, such as a date or location, while another widget might use that information to change the overall presentation.

在 Flutter 中，widget 通过回调得到状态改变的通知，同时当前状态通知给其他 widget 用于显示。重定向这一流程的共同父级是 State，下面稍微复杂的示例显示了它在实践中的工作原理：

In Flutter, change notifications flow “up” the widget hierarchy by way of callbacks, while current state flows “down” to the stateless widgets that do presentation. The common parent that redirects this flow is the State. The following slightly more complex example shows how this works in practice:

import 'package:flutter/material.dart';

class CounterDisplay extends StatelessWidget {
  const CounterDisplay({required this.count, Key? key}) : super(key: key);

  final int count;

  @override
  Widget build(BuildContext context) {
    return Text('Count: $count');
  }
}

class CounterIncrementor extends StatelessWidget {
  const CounterIncrementor({required this.onPressed, Key? key})
      : super(key: key);

  final VoidCallback onPressed;

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: onPressed,
      child: const Text('Increment'),
    );
  }
}

class Counter extends StatefulWidget {
  const Counter({Key? key}) : super(key: key);

  @override
  _CounterState createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  int _counter = 0;

  void _increment() {
    setState(() {
      ++_counter;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Row(
      mainAxisAlignment: MainAxisAlignment.center,
      children: <Widget>[
        CounterIncrementor(onPressed: _increment),
        const SizedBox(width: 16),
        CounterDisplay(count: _counter),
      ],
    );
  }
}

void main() {
  runApp(
    const MaterialApp(
      home: Scaffold(
        body: Center(
          child: Counter(),
        ),
      ),
    ),
  );
}

注意创建两个新的无状态 widget 的方式，它清楚地分离了显示计数器（CounterDisplay）和改变计数器（CounterIncrementor）。尽管最终结果与前面的示例相同，但是责任的分离将更大的复杂性封装在各个 widget 中，保证了父级的简单性。

Notice the creation of two new stateless widgets, cleanly separating the concerns of displaying the counter (CounterDisplay) and changing the counter (CounterIncrementor). Although the net result is the same as the previous example, the separation of responsibility allows greater complexity to be encapsulated in the individual widgets, while maintaining simplicity in the parent.

有关更多信息，请参阅：

For more information, see:

整合在一起

Bringing it all together

下面是一个更完整的示例，汇集了上面介绍的概念：假定一个购物应用显示各种出售的产品，并在购物车中维护想购买的物品。首先定义一个用于展示的类，ShoppingListItem：

What follows is a more complete example that brings together these concepts: A hypothetical shopping application displays various products offered for sale, and maintains a shopping cart for intended purchases. Start by defining the presentation class, ShoppingListItem:

import 'package:flutter/material.dart';

class Product {
  const Product({required this.name});

  final String name;
}

typedef CartChangedCallback = Function(Product product, bool inCart);

class ShoppingListItem extends StatelessWidget {
  ShoppingListItem({
    required this.product,
    required this.inCart,
    required this.onCartChanged,
  }) : super(key: ObjectKey(product));

  final Product product;
  final bool inCart;
  final CartChangedCallback onCartChanged;

  Color _getColor(BuildContext context) {
    // The theme depends on the BuildContext because different
    // parts of the tree can have different themes.
    // The BuildContext indicates where the build is
    // taking place and therefore which theme to use.

    return inCart //
        ? Colors.black54
        : Theme.of(context).primaryColor;
  }

  TextStyle? _getTextStyle(BuildContext context) {
    if (!inCart) return null;

    return const TextStyle(
      color: Colors.black54,
      decoration: TextDecoration.lineThrough,
    );
  }

  @override
  Widget build(BuildContext context) {
    return ListTile(
      onTap: () {
        onCartChanged(product, inCart);
      },
      leading: CircleAvatar(
        backgroundColor: _getColor(context),
        child: Text(product.name[0]),
      ),
      title: Text(product.name, style: _getTextStyle(context)),
    );
  }
}

void main() {
  runApp(
    MaterialApp(
      home: Scaffold(
        body: Center(
          child: ShoppingListItem(
            product: const Product(name: 'Chips'),
            inCart: true,
            onCartChanged: (product, inCart) {},
          ),
        ),
      ),
    ),
  );
}

ShoppingListItem widget 遵循无状态 widget 的通用模式。它将构造函数中接受到的值存储在 final 成员变量中，然后在 build() 函数中使用它们。例如，inCart 布尔值使两种样式进行切换：一个使用当前主题的主要颜色，另一个使用灰色。

The ShoppingListItem widget follows a common pattern for stateless widgets. It stores the values it receives in its constructor in final member variables, which it then uses during its build() function. For example, the inCart boolean toggles between two visual appearances: one that uses the primary color from the current theme, and another that uses gray.

当用户点击列表中的一项，widget 不会直接改变 inCart 的值，而是通过调用从父 widget 接收到的 onCartChanged 函数。这种方式可以在组件的生命周期中存储状态更长久，从而使状态持久化。甚至，widget 传给 runApp() 的状态可以持久到整个应用的生命周期。

When the user taps the list item, the widget doesn’t modify its inCart value directly. Instead, the widget calls the onCartChanged function it received from its parent widget. This pattern lets you store state higher in the widget hierarchy, which causes the state to persist for longer periods of time. In the extreme, the state stored on the widget passed to runApp() persists for the lifetime of the application.

当父级接收到 onCartChanged 回调时，父级会更新其内部状态，从而触发父级重建并使用新的 inCart 值来创建新的 ShoppingListItem 实例。尽管父级在重建时会创建 ShoppingListItem 的新实例，但是由于框架会将新构建的 widget 与先前构建的 widget 进行比较，仅将差异应用于底层的 RenderObject，这种代价是很小的。

When the parent receives the onCartChanged callback, the parent updates its internal state, which triggers the parent to rebuild and create a new instance of ShoppingListItem with the new inCart value. Although the parent creates a new instance of ShoppingListItem when it rebuilds, that operation is cheap because the framework compares the newly built widgets with the previously built widgets and applies only the differences to the underlying RenderObject.

这里有一个示例展示父组件是如何存储可变状态：

Here’s an example parent widget that stores mutable state:

import 'package:flutter/material.dart';

class Product {
  const Product({required this.name});

  final String name;
}

typedef CartChangedCallback = Function(Product product, bool inCart);

class ShoppingListItem extends StatelessWidget {
  ShoppingListItem({
    required this.product,
    required this.inCart,
    required this.onCartChanged,
  }) : super(key: ObjectKey(product));

  final Product product;
  final bool inCart;
  final CartChangedCallback onCartChanged;

  Color _getColor(BuildContext context) {
    // The theme depends on the BuildContext because different
    // parts of the tree can have different themes.
    // The BuildContext indicates where the build is
    // taking place and therefore which theme to use.

    return inCart //
        ? Colors.black54
        : Theme.of(context).primaryColor;
  }

  TextStyle? _getTextStyle(BuildContext context) {
    if (!inCart) return null;

    return const TextStyle(
      color: Colors.black54,
      decoration: TextDecoration.lineThrough,
    );
  }

  @override
  Widget build(BuildContext context) {
    return ListTile(
      onTap: () {
        onCartChanged(product, inCart);
      },
      leading: CircleAvatar(
        backgroundColor: _getColor(context),
        child: Text(product.name[0]),
      ),
      title: Text(
        product.name,
        style: _getTextStyle(context),
      ),
    );
  }
}

class ShoppingList extends StatefulWidget {
  const ShoppingList({required this.products, Key? key}) : super(key: key);

  final List<Product> products;

  // The framework calls createState the first time
  // a widget appears at a given location in the tree.
  // If the parent rebuilds and uses the same type of
  // widget (with the same key), the framework re-uses
  // the State object instead of creating a new State object.

  @override
  _ShoppingListState createState() => _ShoppingListState();
}

class _ShoppingListState extends State<ShoppingList> {
  final _shoppingCart = <Product>{};

  void _handleCartChanged(Product product, bool inCart) {
    setState(() {
      // When a user changes what's in the cart, you need
      // to change _shoppingCart inside a setState call to
      // trigger a rebuild.
      // The framework then calls build, below,
      // which updates the visual appearance of the app.

      if (!inCart) {
        _shoppingCart.add(product);
      } else {
        _shoppingCart.remove(product);
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Shopping List'),
      ),
      body: ListView(
        padding: const EdgeInsets.symmetric(vertical: 8.0),
        children: widget.products.map((Product product) {
          return ShoppingListItem(
            product: product,
            inCart: _shoppingCart.contains(product),
            onCartChanged: _handleCartChanged,
          );
        }).toList(),
      ),
    );
  }
}

void main() {
  runApp(const MaterialApp(
    title: 'Shopping App',
    home: ShoppingList(
      products: [
        Product(name: 'Eggs'),
        Product(name: 'Flour'),
        Product(name: 'Chocolate chips'),
      ],
    ),
  ));
}

ShoppingList 类继承自 StatefulWidget，这意味着这个 widget 存储着可变状态。当 ShoppingList 首次插入到 widget 树中时，框架调用 createState() 函数来创建 _ShoppingListState 的新实例，以与树中的该位置相关联。（注意，State 的子类通常以下划线开头进行命名，表示它们的实现细节是私有的）当该 widget 的父 widget 重建时，父 widget 首先会创建一个 ShoppingList 的实例，但是框架会复用之前创建的 _ShoppingListState，而不会重新调用 createState。

The ShoppingList class extends StatefulWidget, which means this widget stores mutable state. When the ShoppingList widget is first inserted into the tree, the framework calls the createState() function to create a fresh instance of _ShoppingListState to associate with that location in the tree. (Notice that subclasses of State are typically named with leading underscores to indicate that they are private implementation details.) When this widget’s parent rebuilds, the parent creates a new instance of ShoppingList, but the framework reuses the _ShoppingListState instance that is already in the tree rather than calling createState again.

为了访问当前 ShoppingList 的属性， _ShoppingListState 可以使用它的 widget 属性。当父组件重建一个新的 ShoppingList 时， _ShoppingListState 会使用新的 widget 值来创建。如果希望在 widget 属性更改时收到通知，则可以重写 didUpdateWidget() 函数，该函数将 oldWidget 作为参数传递，以便将 oldWidget 与当前 widget 进行比较。

To access properties of the current ShoppingList, the _ShoppingListState can use its widget property. If the parent rebuilds and creates a new ShoppingList, the _ShoppingListState rebuilds with the new widget value. If you wish to be notified when the widget property changes, override the didUpdateWidget() function, which is passed an oldWidget to let you compare the old widget with the current widget.

当处理 onCartChanged 回调时，_ShoppingListState 通过增加或删除 _shoppingCart 中的产品来改变其内部状态。为了通知框架它改变了它的内部状态，需要调用 setState()，将该 widget 标记为「dirty」（脏标记），并且计划在下次应用需要更新屏幕时重新构建它。如果在修改 widget 的内部状态后忘记调用 setState，框架将不知道这个 widget 是「dirty」（脏标记），并且可能不会调用 widget 的 build() 方法，这意味着用户界面可能不会更新以展示新的状态。通过以这种方式管理状态，你不需要编写用于创建和更新子 widget 的单独代码。相反，你只需实现 build 函数，它可以处理这两种情况。

When handling the onCartChanged callback, the _ShoppingListState mutates its internal state by either adding or removing a product from _shoppingCart. To signal to the framework that it changed its internal state, it wraps those calls in a setState() call. Calling setState marks this widget as dirty and schedules it to be rebuilt the next time your app needs to update the screen. If you forget to call setState when modifying the internal state of a widget, the framework won’t know your widget is dirty and might not call the widget’s build() function, which means the user interface might not update to reflect the changed state. By managing state in this way, you don’t need to write separate code for creating and updating child widgets. Instead, you simply implement the build function, which handles both situations.

Responding to widget lifecycle events

在 StatefulWidget 上调用 createState() 之后，框架将新的状态对象插入到树中，然后在状态对象上调用 initState()。 State 的子类可以重写 initState 来完成只需要发生一次的工作。例如，重写 initState 来配置动画或订阅平台服务。实现 initState 需要调用父类的 super.initState 方法来开始。

After calling createState() on the StatefulWidget, the framework inserts the new state object into the tree and then calls initState() on the state object. A subclass of State can override initState to do work that needs to happen just once. For example, override initState to configure animations or to subscribe to platform services. Implementations of initState are required to start by calling super.initState.

当不再需要状态对象时，框架会调用状态对象上的 dispose() 方法。可以重写dispose 方法来清理状态。例如，重写 dispose 以取消计时器或取消订阅平台服务。实现 dispose 时通常通过调用 super.dispose 来结束。

When a state object is no longer needed, the framework calls dispose() on the state object. Override the dispose function to do cleanup work. For example, override dispose to cancel timers or to unsubscribe from platform services. Implementations of dispose typically end by calling super.dispose.

有关更多信息，请参阅 State。

For more information, see State.

Keys

使用 key 可以控制框架在 widget 重建时与哪些其他 widget 进行匹配。默认情况下，框架根据它们的 runtimeType 以及它们的显示顺序来匹配。使用 key 时，框架要求两个 widget 具有相同的 key 和 runtimeType。

Use keys to control which widgets the framework matches up with other widgets when a widget rebuilds. By default, the framework matches widgets in the current and previous build according to their runtimeType and the order in which they appear. With keys, the framework requires that the two widgets have the same key as well as the same runtimeType.

Key 在构建相同类型 widget 的多个实例时很有用。例如，ShoppingList widget，它只构建刚刚好足够的 ShoppingListItem 实例来填充其可见区域：

Keys are most useful in widgets that build many instances of the same type of widget. For example, the ShoppingList widget, which builds just enough ShoppingListItem instances to fill its visible region:

如果没有 key，当前构建中的第一个条目将始终与前一个构建中的第一个条目同步，在语义上，列表中的第一个条目如果滚动出屏幕，那么它应该不会再在窗口中可见。
Without keys, the first entry in the current build would always sync with the first entry in the previous build, even if, semantically, the first entry in the list just scrolled off screen and is no longer visible in the viewport.
通过给列表中的每个条目分配为“语义” key，无限列表可以更高效，因为框架将通过相匹配的语义 key 来同步条目，并因此具有相似（或相同）的可视外观。此外，语义上同步条目意味着在有状态子 widget 中，保留的状态将附加到相同的语义条目上，而不是附加到相同数字位置上的条目。
By assigning each entry in the list a “semantic” key, the infinite list can be more efficient because the framework syncs entries with matching semantic keys and therefore similar (or identical) visual appearances. Moreover, syncing the entries semantically means that state retained in stateful child widgets remains attached to the same semantic entry rather than the entry in the same numerical position in the viewport.

有关更多信息，请参阅 Key API。

For more information, see the Key API.

全局 key

Global keys

全局 key 可以用来标识唯一子 widget。全局 key 在整个 widget 结构中必须是全局唯一的，而不像本地 key 只需要在兄弟 widget 中唯一。由于它们是全局唯一的，因此可以使用全局 key 来检索与 widget 关联的状态。

Use global keys to uniquely identify child widgets. Global keys must be globally unique across the entire widget hierarchy, unlike local keys which need only be unique among siblings. Because they are globally unique, a global key can be used to retrieve the state associated with a widget.

有关更多信息，请参阅 GlobalKey API。

For more information, see the GlobalKey API.

Flutter 中的布局

Flutter 布局的核心机制是 widgets。在 Flutter 中，几乎所有东西都是 widget —— 甚至布局模型都是 widgets。你在 Flutter 应用程序中看到的图像，图标和文本都是 widgets。此外不能直接看到的也是 widgets，例如用来排列、限制和对齐可见 widgets 的行、列和网格。

The core of Flutter’s layout mechanism is widgets. In Flutter, almost everything is a widget—even layout models are widgets. The images, icons, and text that you see in a Flutter app are all widgets. But things you don’t see are also widgets, such as the rows, columns, and grids that arrange, constrain, and align the visible widgets.

你可以通过组合 widgets 来构建更复杂的 widgets 来创建布局。比如，下面第一个截图上有 3 个图标，每个图标下面都有一个标签：

You create a layout by composing widgets to build more complex widgets. For example, the first screenshot below shows 3 icons with a label under each one:

第二个截图显示了可视布局，可以看到有一排三列，其中每列包含一个图标和一个标签。

The second screenshot displays the visual layout, showing a row of 3 columns where each column contains an icon and a label.

以下是这个 UI 的 widget 树形图：

Here’s a diagram of the widget tree for this UI:

Node tree

图上大部分应该和你预想的一样，但你可能会疑惑 containers（图上粉色显示的）是什么。 Container 是一个 widget，允许你自定义其子 widget。举几个例子，如果要添加 padding、margin、边框或背景颜色，你就可以用上 Container 了。

Most of this should look as you might expect, but you might be wondering about the containers (shown in pink). Container is a widget class that allows you to customize its child widget. Use a Container when you want to add padding, margins, borders, or background color, to name some of its capabilities.

在这个例子中，每个 Text widget 都被放在一个 Container 以添加 padding。整个 Row 也被放在一个 Container 中，以便添加 padding。

In this example, each Text widget is placed in a Container to add margins. The entire Row is also placed in a Container to add padding around the row.

这个例子其余部分的 UI 由属性控制。通过 Icon 的 color 属性来设置它的颜色，通过 Text.style 属性来设置文字的字体、颜色、字重等等。列和行有一些属性可以让你指定子项垂直或水平的对齐方式以及子项应占用的空间大小。

The rest of the UI in this example is controlled by properties. Set an Icon’s color using its color property. Use the Text.style property to set the font, its color, weight, and so on. Columns and rows have properties that allow you to specify how their children are aligned vertically or horizontally, and how much space the children should occupy.

Lay out a widget

如何在 Flutter 中布局单个 widget？本节将介绍如何创建和显示单个 widget。本节还包括一个简单的 Hello World app 的完整代码。

How do you lay out a single widget in Flutter? This section shows you how to create and display a simple widget. It also shows the entire code for a simple Hello World app.

在 Flutter 中，只需几步就可以在屏幕上显示文本、图标或图像。

In Flutter, it takes only a few steps to put text, an icon, or an image on the screen.

1. Select a layout widget

根据你想要对齐或限制可见 widget 的方式从各种 layout widgets 中进行选择，因为这些特性通常会传递它所给包含的 widget。

Choose from a variety of layout widgets based on how you want to align or constrain the visible widget, as these characteristics are typically passed on to the contained widget.

本例使用将其内容水平和垂直居中的 Center。

This example uses Center which centers its content horizontally and vertically.

2. Create a visible widget

举个例子，创建一个 Text widget：

For example, create a Text widget:

Text('Hello World'),

创建一个 Image widget：

Create an Image widget:

Image.asset(
  'images/lake.jpg',
  fit: BoxFit.cover,
),

创建一个 Icon widget：

Create an Icon widget:

Icon(
  Icons.star,
  color: Colors.red[500],
),

3. Add the visible widget to the layout widget

所有布局 widgets 都具有以下任一项：

All layout widgets have either of the following:

一个 child 属性，如果它们只包含一个子项 —— 例如 Center 和 Container
A child property if they take a single child—for example, Center or Container
一个 children 属性，如果它们包含多个子项 —— 例如 Row、Column、ListView 和 Stack
A children property if they take a list of widgets—for example, Row, Column, ListView, or Stack.

将 Text widget 添加进 Center widget：

Add the Text widget to the Center widget:

const Center(
  child: Text('Hello World'),
),

4. Add the layout widget to the page

一个 Flutter app 本身就是一个 widget，大多数 widgets 都有一个 build() 方法，在 app 的 build() 方法中实例化和返回一个 widget 会让它显示出来。

A Flutter app is itself a widget, and most widgets have a build() method. Instantiating and returning a widget in the app’s build() method displays the widget.

对于 Material app，你可以使用 Scaffold widget，它提供默认的 banner 背景颜色，还有用于添加抽屉、提示条和底部列表弹窗的 API。你可以将 Center widget 直接添加到主页 body 的属性中。

For a Material app, you can use a Scaffold widget; it provides a default banner, background color, and has API for adding drawers, snack bars, and bottom sheets. Then you can add the Center widget directly to the body property for the home page.

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter layout demo',
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Flutter layout demo'),
        ),
        body: const Center(
          child: Text('Hello World'),
        ),
      ),
    );
  }
}

非 Material apps

Non-Material apps

对于非 Material app，你可以将 Center widget 添加到 app 的 build() 方法里：

For a non-Material app, you can add the Center widget to the app’s build() method:

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Container(
      decoration: const BoxDecoration(color: Colors.white),
      child: const Center(
        child: Text(
          'Hello World',
          textDirection: TextDirection.ltr,
          style: TextStyle(
            fontSize: 32,
            color: Colors.black87,
          ),
        ),
      ),
    );
  }
}

默认情况下，非 Material app 不包含 AppBar、标题和背景颜色。如果你希望在非 Material app 中使用这些功能，则必须自己构建它们。以上 app 将背景颜色更改为白色，将文本更改为深灰色来模拟一个 Material app。

By default a non-Material app doesn’t include an AppBar, title, or background color. If you want these features in a non-Material app, you have to build them yourself. This app changes the background color to white and the text to dark grey to mimic a Material app.

完成! 启动这个 app，你应该能看到 Hello World。

That’s it! When you run the app, you should see Hello World.

App 源码:

App source code:

横向或纵向布局多个 widgets

Lay out multiple widgets vertically and horizontally

最常见的布局模式之一是垂直或水平 widgets。你可以使用 Row widget 水平排列 widgets，使用 Column widget 垂直排列 widgets。

One of the most common layout patterns is to arrange widgets vertically or horizontally. You can use a Row widget to arrange widgets horizontally, and a Column widget to arrange widgets vertically.

要点

What's the point?

Row 和 Column 是两种最常用的布局模式。
Row and Column are two of the most commonly used layout patterns.
Row 和 Column 每个都有一个子 widgets 列表。
Row and Column each take a list of child widgets.
一个子 widget 本身可以是 Row、Column 或其他复杂 widget。
A child widget can itself be a Row, Column, or other complex widget.
可以指定 Row 或 Column 如何在垂直和水平方向上对齐其子项。
You can specify how a Row or Column aligns its children, both vertically and horizontally.
可以拉伸或限制特定的子 widgets。
You can stretch or constrain specific child widgets.
可以指定子 widgets 如何占用 Row 或 Column 的可用空间。
You can specify how child widgets use the Row’s or Column’s available space.

要在 Flutter 中创建行或列，可以将子 widgets 列表添加到 Row 或 Column widget 中。反过来，每个子项本身可以是一行或一列，依此类推。以下示例演示了如何在行或列中嵌套行或列。

To create a row or column in Flutter, you add a list of children widgets to a Row or Column widget. In turn, each child can itself be a row or column, and so on. The following example shows how it is possible to nest rows or columns inside of rows or columns.

这个布局被组织为 Row。这一行包含两个子项：左侧的列和右侧的图像：

This layout is organized as a Row. The row contains two children: a column on the left, and an image on the right:

Screenshot with callouts showing the row containing two children

左侧列的 widget 树嵌套着行和列。

The left column’s widget tree nests rows and columns.

Diagram showing a left column broken down to its sub-rows and sub-columns

你将在嵌套行和列中实现蛋糕介绍示例的一些布局代码。

You’ll implement some of Pavlova’s layout code in Nesting rows and columns.

提示

Row 和 Column 是水平和垂直布局的基本原始 widgets —— 这些低级 widgets 允许最大程度的自定义。 Flutter 还提供专门的、更高级别的 widgets，可能可以直接满足需求。例如，和 Row 相比你可能更喜欢 ListTile，这是一个易于使用的 widget，有属性可以设置头尾图标，最多可以显示 3 行文本；和 Column 相比你也可能更喜欢 ListView，这是一种类似于列的布局，但如果其内容太长导致可用空间不够容纳时会自动滚动。更多信息可以查看通用布局 widgets。

Row and Column are basic primitive widgets for horizontal and vertical layouts—these low-level widgets allow for maximum customization. Flutter also offers specialized, higher level widgets that might be sufficient for your needs. For example, instead of Row you might prefer ListTile, an easy-to-use widget with properties for leading and trailing icons, and up to 3 lines of text. Instead of Column, you might prefer ListView, a column-like layout that automatically scrolls if its content is too long to fit the available space. For more information, see Common layout widgets.

对齐 widgets

Aligning widgets

你可以使用 mainAxisAlignment 和 crossAxisAlignment 属性控制行或列如何对齐其子项。对于一行来说，主轴水平延伸，交叉轴垂直延伸。对于一列来说，主轴垂直延伸，交叉轴水平延伸。

You control how a row or column aligns its children using the mainAxisAlignment and crossAxisAlignment properties. For a row, the main axis runs horizontally and the cross axis runs vertically. For a column, the main axis runs vertically and the cross axis runs horizontally.

Diagram showing the main axis and cross axis for a row

Diagram showing the main axis and cross axis for a column

MainAxisAlignment 和 CrossAxisAlignment 这两个类提供了很多用于控制对齐的常量。

The MainAxisAlignment and CrossAxisAlignment classes offer a variety of constants for controlling alignment.

在以下示例中，3 个图像每个都是是 100 像素宽。渲染框（在本例中是整个屏幕）宽度超过 300 像素，因此设置主轴对齐方式为 spaceEvenly 会将空余空间在每个图像之间、之前和之后均匀地划分。

In the following example, each of the 3 images is 100 pixels wide. The render box (in this case, the entire screen) is more than 300 pixels wide, so setting the main axis alignment to spaceEvenly divides the free horizontal space evenly between, before, and after each image.

Row(
  mainAxisAlignment: MainAxisAlignment.spaceEvenly,
  children: [
    Image.asset('images/pic1.jpg'),
    Image.asset('images/pic2.jpg'),
    Image.asset('images/pic3.jpg'),
  ],
);

Row with 3 evenly spaced images

App 源码: row_column

App source: row_column

列的工作方式与行的工作方式相同。以下示例展示了包含 3 个图像的列，每个图像的高度为 100 像素。渲染框（在本例中是整个屏幕）高度超过 300 像素，因此设置主轴对齐方式为 spaceEvenly 会将空余空间在每个图像之间、之上和之下均匀地划分。

Columns work the same way as rows. The following example shows a column of 3 images, each is 100 pixels high. The height of the render box (in this case, the entire screen) is more than 300 pixels, so setting the main axis alignment to spaceEvenly divides the free vertical space evenly between, above, and below each image.

Column(
  mainAxisAlignment: MainAxisAlignment.spaceEvenly,
  children: [
    Image.asset('images/pic1.jpg'),
    Image.asset('images/pic2.jpg'),
    Image.asset('images/pic3.jpg'),
  ],
);

App 源码: row_column

App source: row_column

调整 widgets 大小

Sizing widgets

当某个布局太大而超出屏幕时，受影响的边缘会出现黄色和黑色条纹图案。这里有一个行太宽的例子：

When a layout is too large to fit a device, a yellow and black striped pattern appears along the affected edge. Here is an example of a row that is too wide:

Overly-wide row

通过使用 Expanded widget，可以调整 widgets 的大小以适合行或列。要修复上一个图像行对其渲染框来说太宽的示例，可以用 Expanded widget 把每个图像包起来。

Widgets can be sized to fit within a row or column by using the Expanded widget. To fix the previous example where the row of images is too wide for its render box, wrap each image with an Expanded widget.

Row(
  crossAxisAlignment: CrossAxisAlignment.center,
  children: [
    Expanded(
      child: Image.asset('images/pic1.jpg'),
    ),
    Expanded(
      child: Image.asset('images/pic2.jpg'),
    ),
    Expanded(
      child: Image.asset('images/pic3.jpg'),
    ),
  ],
);

Row of 3 images that are too wide, but each is constrained to take only 1/3 of the space

App 源码: sizing

App source: sizing

也许你想要一个 widget 占用的空间是兄弟项的两倍。为了达到这个效果，可以使用 Expanded widget 的 flex 属性，这是一个用来确定 widget 的弹性系数的整数。默认的弹性系数为 1，以下代码将中间图像的弹性系数设置为 2：

Perhaps you want a widget to occupy twice as much space as its siblings. For this, use the Expanded widget flex property, an integer that determines the flex factor for a widget. The default flex factor is 1. The following code sets the flex factor of the middle image to 2:

Row(
  crossAxisAlignment: CrossAxisAlignment.center,
  children: [
    Expanded(
      child: Image.asset('images/pic1.jpg'),
    ),
    Expanded(
      flex: 2,
      child: Image.asset('images/pic2.jpg'),
    ),
    Expanded(
      child: Image.asset('images/pic3.jpg'),
    ),
  ],
);

Row of 3 images with the middle image twice as wide as the others

App 源码: sizing

App source: sizing

组合 widgets

Packing widgets

默认情况下，行或列沿其主轴会占用尽可能多的空间，但如果要将子项紧密组合在一起，请将其 mainAxisSize 设置为 MainAxisSize.min。以下示例使用此属性将星形图标组合在一起。

By default, a row or column occupies as much space along its main axis as possible, but if you want to pack the children closely together, set its mainAxisSize to MainAxisSize.min. The following example uses this property to pack the star icons together.

Row(
  mainAxisSize: MainAxisSize.min,
  children: [
    Icon(Icons.star, color: Colors.green[500]),
    Icon(Icons.star, color: Colors.green[500]),
    Icon(Icons.star, color: Colors.green[500]),
    const Icon(Icons.star, color: Colors.black),
    const Icon(Icons.star, color: Colors.black),
  ],
)

Row of 5 stars, packed together in the middle of the row

App 源码: pavlova

App source: pavlova

嵌套行和列

Nesting rows and columns

布局框架允许你根据需要在行和列内嵌套行和列。让我们看看以下布局的概述部分的代码：

The layout framework allows you to nest rows and columns inside of rows and columns as deeply as you need. Let’s look at the code for the outlined section of the following layout:

Screenshot of the pavlova app, with the ratings and icon rows outlined in red

概述的部分实现为两行，评级一行包含五颗星和评论的数量，图标一行包含由图标与文本组成的三列。

The outlined section is implemented as two rows. The ratings row contains five stars and the number of reviews. The icons row contains three columns of icons and text.

以下是评级行的 widget 树形图：

The widget tree for the ratings row:

ratings 变量创建了一个行，其中包含较小的由 5 个星形图标和文本组成的一行：

The ratings variable creates a row containing a smaller row of 5 star icons, and text:

var stars = Row(
  mainAxisSize: MainAxisSize.min,
  children: [
    Icon(Icons.star, color: Colors.green[500]),
    Icon(Icons.star, color: Colors.green[500]),
    Icon(Icons.star, color: Colors.green[500]),
    const Icon(Icons.star, color: Colors.black),
    const Icon(Icons.star, color: Colors.black),
  ],
);

final ratings = Container(
  padding: const EdgeInsets.all(20),
  child: Row(
    mainAxisAlignment: MainAxisAlignment.spaceEvenly,
    children: [
      stars,
      const Text(
        '170 Reviews',
        style: TextStyle(
          color: Colors.black,
          fontWeight: FontWeight.w800,
          fontFamily: 'Roboto',
          letterSpacing: 0.5,
          fontSize: 20,
        ),
      ),
    ],
  ),
);

评级行下方的图标行包含 3 列，每列包含一个图标和两行文本，你可以在其 widget 树中看到：

The icons row, below the ratings row, contains 3 columns; each column contains an icon and two lines of text, as you can see in its widget tree:

iconList 变量定义了图标行:

The iconList variable defines the icons row:

const descTextStyle = TextStyle(
  color: Colors.black,
  fontWeight: FontWeight.w800,
  fontFamily: 'Roboto',
  letterSpacing: 0.5,
  fontSize: 18,
  height: 2,
);

// DefaultTextStyle.merge() allows you to create a default text
// style that is inherited by its child and all subsequent children.
final iconList = DefaultTextStyle.merge(
  style: descTextStyle,
  child: Container(
    padding: const EdgeInsets.all(20),
    child: Row(
      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
      children: [
        Column(
          children: [
            Icon(Icons.kitchen, color: Colors.green[500]),
            const Text('PREP:'),
            const Text('25 min'),
          ],
        ),
        Column(
          children: [
            Icon(Icons.timer, color: Colors.green[500]),
            const Text('COOK:'),
            const Text('1 hr'),
          ],
        ),
        Column(
          children: [
            Icon(Icons.restaurant, color: Colors.green[500]),
            const Text('FEEDS:'),
            const Text('4-6'),
          ],
        ),
      ],
    ),
  ),
);

leftColumn 变量包含评级和图标行，以及蛋糕介绍的标题和文本：

The leftColumn variable contains the ratings and icons rows, as well as the title and text that describes the Pavlova:

final leftColumn = Container(
  padding: const EdgeInsets.fromLTRB(20, 30, 20, 20),
  child: Column(
    children: [
      titleText,
      subTitle,
      ratings,
      iconList,
    ],
  ),
);

左列放置在 Container 中以限制其宽度。最后，UI 由 Card 内的整行（包含左列和图像）构成。

The left column is placed in a SizedBox to constrain its width. Finally, the UI is constructed with the entire row (containing the left column and the image) inside a Card.

蛋糕图片来自 Pixabay 网站。你可以使用 Image.network() 从网络上引用图像，但是在本例图像将保存到项目中的一个图像目录中，添加到 pubspec 文件，并使用 Images.asset() 访问。更多信息可以查看文档中关于添加资源和图片这一章。

The Pavlova image is from Pixabay. You can embed an image from the net using Image.network() but, for this example, the image is saved to an images directory in the project, added to the pubspec file, and accessed using Images.asset(). For more information, see Adding assets and images.

body: Center(
  child: Container(
    margin: const EdgeInsets.fromLTRB(0, 40, 0, 30),
    height: 600,
    child: Card(
      child: Row(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          SizedBox(
            width: 440,
            child: leftColumn,
          ),
          mainImage,
        ],
      ),
    ),
  ),
),

小提示

蛋糕介绍的例子在宽屏设备（如平板电脑）上横向运行效果最佳。如果在 iOS 模拟器中运行这个示例，可以使用 Hardware > Device 菜单选择不同的设备。在本例中，我们推荐 iPad Pro。你可以使用 Hardware > Rotate 将其方向更改为横向模式。你还可以使用 Window > Scale 更改模拟器窗口的大小（不改变逻辑像素的数量）。

The Pavlova example runs best horizontally on a wide device, such as a tablet. If you are running this example in the iOS simulator, you can select a different device using the Hardware > Device menu. For this example, we recommend the iPad Pro. You can change its orientation to landscape mode using Hardware > Rotate. You can also change the size of the simulator window (without changing the number of logical pixels) using Window > Scale.

App 源码: pavlova

App source: pavlova

通用布局 widgets

Common layout widgets

Flutter 有一个丰富的布局 widget 仓库，里面有很多经常会用到的布局 widget。目的是为了让你更快的上手，而不是被一个完整的列表吓跑。关于其他有用的 widget 的信息，可以参考 Widget 目录，或者使用 API 参考文档中的搜索框。而且，API 文档中的 widget 页面中经常会给出一些关于相似的 widget 哪个会更适合你的建议。

Flutter has a rich library of layout widgets. Here are a few of those most commonly used. The intent is to get you up and running as quickly as possible, rather than overwhelm you with a complete list. For information on other available widgets, refer to the Widget catalog, or use the Search box in the API reference docs. Also, the widget pages in the API docs often make suggestions about similar widgets that might better suit your needs.

下面的 widget 会分为两类：widgets 库中的标准 widgets 和 Material 库中的 widgets。任何 app 都可以使用 widget 库，但是 Material 库中的组件只能在 Material app 中使用。

The following widgets fall into two categories: standard widgets from the widgets library, and specialized widgets from the Material library. Any app can use the widgets library but only Material apps can use the Material Components library.

标准 widgets

Standard widgets

Container：向 widget 增加 padding、margins、borders、background color 或者其他的“装饰”。
Container: Adds padding, margins, borders, background color, or other decorations to a widget.
GridView：将 widget 展示为一个可滚动的网格。
GridView: Lays widgets out as a scrollable grid.
ListView：将 widget 展示为一个可滚动的列表。
ListView: Lays widgets out as a scrollable list.
Stack：将 widget 覆盖在另一个的上面。
Stack: Overlaps a widget on top of another.

Material widgets

Card：将相关信息整理到一个有圆角和阴影的盒子中。
Card: Organizes related info into a box with rounded corners and a drop shadow.
ListTile：将最多三行的文本、可选的导语以及后面的图标组织在一行中。
ListTile: Organizes up to 3 lines of text, and optional leading and trailing icons, into a row.

Container

许多布局都可以随意的用 Container，它可以将使用了 padding 或者增加了 borders/margins 的 widget 分开。你可以通过将整个布局放到一个 Container 中，并且改变它的背景色或者图片，来改变设备的背景。

Many layouts make liberal use of Containers to separate widgets using padding, or to add borders or margins. You can change the device’s background by placing the entire layout into a Container and changing its background color or image.

摘要 (Container)

Summary (Container)

增加 padding、margins、borders
Add padding, margins, borders
改变背景色或者图片
Change background color or image
只包含一个子 widget，但是这个子 widget 可以是行、列或者是 widget 树的根 widget
Contains a single child widget, but that child can be a Row, Column, or even the root of a widget tree

Diagram showing: margin, border, padding, and content

示例 (Container)

Examples (Container)

这个布局包含一个有两行的列，每行有两张图片。 Container 用来将列的背景色变为浅灰色。

This layout consists of a column with two rows, each containing 2 images. A Container is used to change the background color of the column to a lighter grey.

Widget _buildImageColumn() {
  return Container(
    decoration: const BoxDecoration(
      color: Colors.black26,
    ),
    child: Column(
      children: [
        _buildImageRow(1),
        _buildImageRow(3),
      ],
    ),
  );
}

Screenshot showing 2 rows, each containing 2 images

Container 还用来为每个图片添加圆角和外边距：

A Container is also used to add a rounded border and margins to each image:

Widget _buildDecoratedImage(int imageIndex) => Expanded(
      child: Container(
        decoration: BoxDecoration(
          border: Border.all(width: 10, color: Colors.black38),
          borderRadius: const BorderRadius.all(Radius.circular(8)),
        ),
        margin: const EdgeInsets.all(4),
        child: Image.asset('images/pic$imageIndex.jpg'),
      ),
    );

Widget _buildImageRow(int imageIndex) => Row(
      children: [
        _buildDecoratedImage(imageIndex),
        _buildDecoratedImage(imageIndex + 1),
      ],
    );

你可以在布局构建教程和 Flutter Gallery 中可以发现更多关于 Container 的例子。

You can find more Container examples in the tutorial and the Flutter Gallery (running app, repo).

App 源码: container

App source: container

GridView

使用 GridView 将 widget 作为二维列表展示。 GridView 提供两个预制的列表，或者你可以自定义网格。当 GridView 检测到内容太长而无法适应渲染盒时，它就会自动支持滚动。

Use GridView to lay widgets out as a two-dimensional list. GridView provides two pre-fabricated lists, or you can build your own custom grid. When a GridView detects that its contents are too long to fit the render box, it automatically scrolls.

摘要 (GridView)

Summary (GridView)

在网格中使用 widget
Lays widgets out in a grid
当列的内容超出渲染容器的时候，它会自动支持滚动。
Detects when the column content exceeds the render box and automatically provides scrolling
创建自定义的网格，或者使用下面提供的网格的其中一个：
Build your own custom grid, or use one of the provided grids:
- GridView.count 允许你制定列的数量
  GridView.count allows you to specify the number of columns
- GridView.extent 允许你制定单元格的最大宽度
  GridView.extent allows you to specify the maximum pixel width of a tile

示例 (GridView)

Examples (GridView)

A 3-column grid of photos

使用 GridView.extent 创建一个最大宽度为 150 像素的网格。

Uses GridView.extent to create a grid with tiles a maximum 150 pixels wide.

App 源码： grid_and_list

App source: grid_and_list

A 2 column grid with footers

使用 GridView.count 创建一个网格，它在竖屏模式下有两行，在横屏模式下有三行。可以通过为每个 GridTile 设置 footer 属性来创建标题。

Uses GridView.count to create a grid that’s 2 tiles wide in portrait mode, and 3 tiles wide in landscape mode. The titles are created by setting the footer property for each GridTile.

Dart 代码： Flutter Gallery 中的 grid_list_demo.dart

Dart code: grid_list_demo.dart from the Flutter Gallery。

Widget _buildGrid() => GridView.extent(
    maxCrossAxisExtent: 150,
    padding: const EdgeInsets.all(4),
    mainAxisSpacing: 4,
    crossAxisSpacing: 4,
    children: _buildGridTileList(30));

// The images are saved with names pic0.jpg, pic1.jpg...pic29.jpg.
// The List.generate() constructor allows an easy way to create
// a list when objects have a predictable naming pattern.
List<Container> _buildGridTileList(int count) => List.generate(
    count, (i) => Container(child: Image.asset('images/pic$i.jpg')));

ListView

ListView，一个和列很相似的 widget，当内容长于自己的渲染盒时，就会自动支持滚动。

ListView, a column-like widget, automatically provides scrolling when its content is too long for its render box.

摘要 (ListView)

Summary (ListView)

一个用来组织盒子中列表的专用 Column
A specialized Column for organizing a list of boxes
可以水平或者垂直布局
Can be laid out horizontally or vertically
当监测到空间不足时，会提供滚动
Detects when its content won’t fit and provides scrolling
比 Column 的配置少，使用更容易，并且支持滚动
Less configurable than Column, but easier to use and supports scrolling

示例 (ListView)

Examples (ListView)

ListView containing movie theaters and restaurants

使用 ListView 的业务列表，它使用了多个 ListTile。Divider 将餐厅从剧院中分隔开。

Uses ListView to display a list of businesses using ListTiles. A Divider separates the theaters from the restaurants.

App 源码： grid_and_list

App source: grid_and_list

ListView containing shades of blue

使用 ListView 展示特定颜色系列 Material Design 调色板中的 Colors。

Uses ListView to display the Colors from the Material Design palette for a particular color family.

Dart 代码： Flutter Gallery 中的 colors_demo.dart

Dart code: colors_demo.dart from the Flutter Gallery

Widget _buildList() {
  return ListView(
    children: [
      _tile('CineArts at the Empire', '85 W Portal Ave', Icons.theaters),
      _tile('The Castro Theater', '429 Castro St', Icons.theaters),
      _tile('Alamo Drafthouse Cinema', '2550 Mission St', Icons.theaters),
      _tile('Roxie Theater', '3117 16th St', Icons.theaters),
      _tile('United Artists Stonestown Twin', '501 Buckingham Way',
          Icons.theaters),
      _tile('AMC Metreon 16', '135 4th St #3000', Icons.theaters),
      const Divider(),
      _tile('K\'s Kitchen', '757 Monterey Blvd', Icons.restaurant),
      _tile('Emmy\'s Restaurant', '1923 Ocean Ave', Icons.restaurant),
      _tile(
          'Chaiya Thai Restaurant', '272 Claremont Blvd', Icons.restaurant),
      _tile('La Ciccia', '291 30th St', Icons.restaurant),
    ],
  );
}

ListTile _tile(String title, String subtitle, IconData icon) {
  return ListTile(
    title: Text(title,
        style: const TextStyle(
          fontWeight: FontWeight.w500,
          fontSize: 20,
        )),
    subtitle: Text(subtitle),
    leading: Icon(
      icon,
      color: Colors.blue[500],
    ),
  );
}

Stack

可以使用 Stack 在基础 widget（通常是图片）上排列 widget， widget 可以完全或者部分覆盖基础 widget。

Use Stack to arrange widgets on top of a base widget—often an image. The widgets can completely or partially overlap the base widget.

摘要 (Stack)

Summary (Stack)

用于覆盖另一个 widget
Use for widgets that overlap another widget
子列表中的第一个 widget 是基础 widget；后面的子项覆盖在基础 widget 的顶部
The first widget in the list of children is the base widget; subsequent children are overlaid on top of that base widget
Stack 的内容是无法滚动的
A Stack’s content can’t scroll
你可以剪切掉超出渲染框的子项
You can choose to clip children that exceed the render box

示例 (Stack)

Examples (Stack)

Circular avatar image with a label

在 CircleAvatar 的上面使用 Stack 覆盖 Container （在透明的黑色背景上展示它的 Text）。 Stack 使用 alignment 属性和 Alignment 让文本偏移。

Uses Stack to overlay a Container (that displays its Text on a translucent black background) on top of a CircleAvatar. The Stack offsets the text using the alignment property and Alignments.

App 源码： card_and_stack

App source: card_and_stack

An image with a grey gradient across the top

使用 Stack 将渐变叠加到图片的顶部，渐变可以将工具栏的图标和图片区分开来。

Uses Stack to overlay a gradient to the top of the image. The gradient ensures that the toolbar’s icons are distinct against the image.

Dart 代码： Flutter Gallery 中的 contacts_demo.dart

Dart code: contacts_demo.dart from the Flutter Gallery

Widget _buildStack() {
  return Stack(
    alignment: const Alignment(0.6, 0.6),
    children: [
      const CircleAvatar(
        backgroundImage: AssetImage('images/pic.jpg'),
        radius: 100,
      ),
      Container(
        decoration: const BoxDecoration(
          color: Colors.black45,
        ),
        child: const Text(
          'Mia B',
          style: TextStyle(
            fontSize: 20,
            fontWeight: FontWeight.bold,
            color: Colors.white,
          ),
        ),
      ),
    ],
  );
}

Card

Material 库中的 Card 包含相关有价值的信息，几乎可以由任何 widget 组成，但是通常和 ListTile 一起使用。 Card 只有一个子项，这个子项可以是列、行、列表、网格或者其他支持多个子项的 widget。默认情况下，Card 的大小是 0x0 像素。你可以使用 SizedBox 控制 card 的大小。

A Card, from the Material library, contains related nuggets of information and can be composed from almost any widget, but is often used with ListTile. Card has a single child, but its child can be a column, row, list, grid, or other widget that supports multiple children. By default, a Card shrinks its size to 0 by 0 pixels. You can use SizedBox to constrain the size of a card.

在 Flutter 中，Card 有轻微的圆角和阴影来使它具有 3D 效果。改变 Card 的 elevation 属性可以控制阴影效果。例如，把 elevation 设置为 24，可以从视觉上更多的把 Card 抬离表面，使阴影变得更加分散。关于支持的 elevation 的值的列表，可以查看 Material guidelines 中的 Elevation。使用不支持的值则会使阴影无效。

In Flutter, a Card features slightly rounded corners and a drop shadow, giving it a 3D effect. Changing a Card’s elevation property allows you to control the drop shadow effect. Setting the elevation to 24, for example, visually lifts the Card further from the surface and causes the shadow to become more dispersed. For a list of supported elevation values, see Elevation in the Material guidelines. Specifying an unsupported value disables the drop shadow entirely.

摘要 (Card)

Summary (Card)

实现一个 Material card
Implements a Material card
用于呈现相关有价值的信息
Used for presenting related nuggets of information
接收单个子项，但是子项可以是 Row、Column 或者其他可以包含列表子项的 widget
Accepts a single child, but that child can be a Row, Column, or other widget that holds a list of children
显示圆角和阴影
Displayed with rounded corners and a drop shadow
Card 的内容无法滚动
A Card’s content can’t scroll
来自 Material 库
From the Material library

示例 (Card)

Examples (Card)

Card containing 3 ListTiles

包含 3 个 ListTile 的 Card，并且通过被 SizedBox 包住来调整大小。 Divider 分隔了第一个和第二个 ListTiles。

A Card containing 3 ListTiles and sized by wrapping it with a SizedBox. A Divider separates the first and second ListTiles.

App 源码： card_and_stack

App source: card_and_stack

Card containing an image, text and buttons

包含图片和文本的 Card。

A Card containing an image and text.

Dart 代码： Flutter Gallery 中的 cards_demo.dart

Dart code: cards_demo.dart from the Flutter Gallery

Widget _buildCard() {
  return SizedBox(
    height: 210,
    child: Card(
      child: Column(
        children: [
          ListTile(
            title: const Text(
              '1625 Main Street',
              style: TextStyle(fontWeight: FontWeight.w500),
            ),
            subtitle: const Text('My City, CA 99984'),
            leading: Icon(
              Icons.restaurant_menu,
              color: Colors.blue[500],
            ),
          ),
          const Divider(),
          ListTile(
            title: const Text(
              '(408) 555-1212',
              style: TextStyle(fontWeight: FontWeight.w500),
            ),
            leading: Icon(
              Icons.contact_phone,
              color: Colors.blue[500],
            ),
          ),
          ListTile(
            title: const Text('costa@example.com'),
            leading: Icon(
              Icons.contact_mail,
              color: Colors.blue[500],
            ),
          ),
        ],
      ),
    ),
  );
}

ListTile

ListTile 是 Material 库中专用的行 widget，它可以很轻松的创建一个包含三行文本以及可选的行前和行尾图标的行。 ListTile 在 Card 或者 ListView 中最常用，但是也可以在别处使用。

Use ListTile, a specialized row widget from the Material library, for an easy way to create a row containing up to 3 lines of text and optional leading and trailing icons. ListTile is most commonly used in Card or ListView, but can be used elsewhere.

摘要 (ListTile)

Summary (ListTile)

一个可以包含最多 3 行文本和可选的图标的专用的行
A specialized row that contains up to 3 lines of text and optional icons
比 Row 更少的配置，更容易使用
Less configurable than Row, but easier to use
来自 Material 库
From the Material library

示例 (ListTile)

Examples (ListTile)

Card containing 3 ListTiles

包含 3 个 ListTiles 的 Card。

A Card containing 3 ListTiles.

App 源码： card_and_stack

App source: card_and_stack

3 ListTiles, each containing a pull-down button

使用 ListTile 列出 3 个下拉按钮类型。

Uses ListTile to list 3 drop down button types.

Dart 代码： Flutter Gallery 中的 buttons_demo.dart

Dart code: buttons_demo.dart from the Flutter Gallery

Constraints

To fully understand Flutter’s layout system, you need to learn how Flutter positions and sizes the components in a layout. For more information, see Understanding constraints.

视频

Videos

下面的视频是 Flutter in Focus 系列的一部分，解释了 Stateless 和 Stateful 的 widget。

The following videos, part of the Flutter in Focus series, explain Stateless and Stateful widgets.

Flutter in Focus playlist

每周 Widget 系列的每一集都会介绍一个 widget。其中也包括一些布局的 widget。

Each episode of the Widget of the Week series focuses on a widget. Several of them includes layout widgets.

Flutter Widget of the Week playlist

其他资源

Other resources

当写布局代码时，下面的资源可能会帮助到你。

The following resources might help when writing layout code.

Layout 教程)
学习如何构建布局。
Layout tutorial
Learn how to build a layout.
核心 Widget 目录
描述了 Flutter 中很多可用的 widget。
Widget catalog
Describes many of the widgets available in Flutter.
给 Web 开发者的 Flutter 指南
对那些熟悉 web 开发的人来说，这页将 HTML/CSS 的功能映射到 Flutter 特性上。
HTML/CSS Analogs in Flutter
For those familiar with web programming, this page maps HTML/CSS functionality to Flutter features.
Flutter Gallery 应用和代码仓库
Demo app 展示了很多 Material Design widget 和其他的 Flutter 特性。
Flutter Gallery running app, repo
Demo app showcasing many Material Design widgets and other Flutter features.
Flutter API 文档
所有 Flutter 库的参考文档。
API reference docs
Reference documentation for all of the Flutter libraries.
处理边界约束 (Box constraints) 的问题
讨论 widget 是如何受渲染框限制的。
Dealing with Box Constraints in Flutter
Discusses how widgets are constrained by their render boxes.
在 Flutter 中添加资源和图片
解释在你的 app 中如何添加图片和其他资源。
Adding assets and images
Explains how to add images and other assets to your app’s package.
Flutter 从 0 到 1
一位开发者第一次写 Flutter app 的经验分享文章。
Zero to One with Flutter
One person’s experience writing his first Flutter app.

布局构建教程

第一步: 创建 app 基础代码
Step 0: Create the app base code
第一步: 对布局进行图形分解
Step 1: Diagram the layout
第二步: 实现标题行
Step 2: Implement the title row
第三步: 实现按钮行
Step 3: Implement the button row
第四步: 实现文本区域
Step 4: Implement the text section
第五步: 实现图片区域
Step 5: Implement the image section
第六步: 最终的收尾
Step 6: Final touch

这是一份如何在 Flutter 中构建布局的指南。你将为如下 app 创建布局：

This is a guide to building layouts in Flutter. You’ll build the layout for the following app:

这份指南之前溯源一步解释了 Flutter 中的布局方式，以及展示了如何在屏幕中放置单个 widget。经过了如何水平以及竖直放置 widgets 的讨论之后，一些最常使用的 widgets 都涉及到了。

This guide then takes a step back to explain Flutter’s approach to layout, and shows how to place a single widget on the screen. After a discussion of how to lay widgets out horizontally and vertically, some of the most common layout widgets are covered.

如果你想对布局机制有个”全局”的理解，可以先从 Flutter 中的布局开始.

If you want a “big picture” understanding of the layout mechanism, start with Flutter’s approach to layout.

第一步: 创建 app 基础代码

Step 0: Create the app base code

确保你已经安装和配置好了你的环境，然后做如下步骤：

Make sure to set up your environment, then do the following:

创建一个简单的 Flutter app ——”Hello World”。
Create a basic “Hello World” Flutter app.

按照如下方法修改 app 标题栏的标题以及 app 的标题：

Change the app bar title and the app title as follows:

layout/base/lib/{main_starter.dart → main.dart} Viewed

@@ -12,10 +12,10 @@
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
-      title: 'Welcome to Flutter',
+      title: 'Flutter layout demo',
       home: Scaffold(
         appBar: AppBar(
-          title: const Text('Welcome to Flutter'),
+          title: const Text('Flutter layout demo'),
         ),
         body: const Center(
           child: Text('Hello World'),

第一步: 对布局进行图形分解

Step 1: Diagram the layout

第一步需要将布局分解成它的各个基础元素：

The first step is to break the layout down to its basic elements:

识别出它的行和列。
Identify the rows and columns.
这个布局是否包含网格布局？
Does the layout include a grid?
是否有重叠的元素？
Are there overlapping elements?
界面是否需要选项卡？
Does the UI need tabs?
留意需要对齐、内间距、或者边界的区域。
Notice areas that require alignment, padding, or borders.

首先，识别出稍大的元素。在这个例子中，四个元素排成一列：一个图像，两个行区域，和一个文本区域。

First, identify the larger elements. In this example, four elements are arranged into a column: an image, two rows, and a block of text.

接着，对每一行进行图解。第一行，也就是标题区域，有三个子元素：一个文本列，一个星形图标，和一个数字。它的第一个子元素，文本列，包含两行文本。第一列占据大量空间，因此它应当被封装在一个 Expanded widget 当中。

Next, diagram each row. The first row, called the Title section, has 3 children: a column of text, a star icon, and a number. Its first child, the column, contains 2 lines of text. That first column takes a lot of space, so it must be wrapped in an Expanded widget.

第二行，也就是按钮区域，同样有三个子元素：每个子元素是一个包含图标和文本的列。

The second row, called the Button section, also has 3 children: each child is a column that contains an icon and text.

一旦图解好布局，采取自下而上的方法来实现它就变得尤为轻松了。为了最大程度减少，深层嵌套的布局代码带来的视觉混乱，需要用一些变量和函数来替代某些实现。

Once the layout has been diagrammed, it’s easiest to take a bottom-up approach to implementing it. To minimize the visual confusion of deeply nested layout code, place some of the implementation in variables and functions.

第二步: 实现标题行

Step 2: Implement the title row

首先，你可以构建标题部分左侧列。添加如下代码到 MyApp 类的 build() 方法内顶部。

First, you’ll build the left column in the title section. Add the following code at the top of the build() method of the MyApp class:

Widget titleSection = Container(
  padding: const EdgeInsets.all(32),
  child: Row(
    children: [
      Expanded(
        /*1*/
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            /*2*/
            Container(
              padding: const EdgeInsets.only(bottom: 8),
              child: const Text(
                'Oeschinen Lake Campground',
                style: TextStyle(
                  fontWeight: FontWeight.bold,
                ),
              ),
            ),
            Text(
              'Kandersteg, Switzerland',
              style: TextStyle(
                color: Colors.grey[500],
              ),
            ),
          ],
        ),
      ),
      /*3*/
      Icon(
        Icons.star,
        color: Colors.red[500],
      ),
      const Text('41'),
    ],
  ),
);

将 Column 元素放到 Expanded widget 中可以拉伸该列，以利用该行中所有剩余的闲置空间。设置 crossAxisAlignment 属性值为 CrossAxisAlignment.start，这会将该列放置在行的起始位置。
Putting a Column inside an Expanded widget stretches the column to use all remaining free space in the row. Setting the crossAxisAlignment property to CrossAxisAlignment.start positions the column at the start of the row.
将第一行文本放入 Container 容器中使得你可以增加内间距。列中的第二个子元素，同样为文本，显示为灰色。
Putting the first row of text inside a Container enables you to add padding. The second child in the Column, also text, displays as grey.
标题行中的最后两项是一个红色星形图标，和文字”41”。整行都在一个 Container 容器布局中，而且每条边都有 32 像素的内间距。
The last two items in the title row are a star icon, painted red, and the text “41”. The entire row is in a Container and padded along each edge by 32 pixels. Add the title section to the app body like this:

如下添加标题部分到 app body 中：

Add the title section to the app body like this:

{../base → step2}/lib/main.dart Viewed

@@ -14,11 +48,13 @@
     return MaterialApp(
       title: 'Flutter layout demo',
       home: Scaffold(
         appBar: AppBar(
           title: const Text('Flutter layout demo'),
         ),
-        body: const Center(
- child: Text('Hello World'),
+        body: Column(
+ children: [
+            titleSection,
+          ],
         ),
       ),
     );

第三步: 实现按钮行

Step 3: Implement the button row

按钮区域包含三列使用相同布局－一行文本上面一个图标。此行的各列被等间隙放置，文本和图标被着以初始色。

The button section contains 3 columns that use the same layout—an icon over a row of text. The columns in this row are evenly spaced, and the text and icons are painted with the primary color.

由于构建每列的代码基本相同，因此可以创建一个名为 buildButtonColumn() 的私有辅助函数，以颜色、图标和文本为入参，返回一个以指定颜色绘制自身 widgets 的一个 column 列对象。

Since the code for building each column is almost identical, create a private helper method named buildButtonColumn(), which takes a color, an Icon and Text, and returns a column with its widgets painted in the given color.

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // ···
  }

  Column _buildButtonColumn(Color color, IconData icon, String label) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Icon(icon, color: color),
        Container(
          margin: const EdgeInsets.only(top: 8),
          child: Text(
            label,
            style: TextStyle(
              fontSize: 12,
              fontWeight: FontWeight.w400,
              color: color,
            ),
          ),
        ),
      ],
    );
  }
}

这个函数直接将图标添加到这列里。文本在以一个仅有上间距的 Container 容器中，使得文本与图标分隔开。

The function adds the icon directly to the column. The text is inside a Container with a top-only margin, separating the text from the icon.

通过调用函数并传递针对某列的颜色，Icon 图标和文本，来构建包含这些列的行。然后在行的主轴方向通过使用 MainAxisAlignment.spaceEvenly，将剩余的空间均分到每列各自的前后及中间。只需在 build() 方法中的 titleSection 声明下添加如下代码：

Build the row containing these columns by calling the function and passing the color, Icon, and text specific to that column. Align the columns along the main axis using MainAxisAlignment.spaceEvenly to arrange the free space evenly before, between, and after each column. Add the following code just below the titleSection declaration inside the build() method:

Color color = Theme.of(context).primaryColor;

Widget buttonSection = Row(
  mainAxisAlignment: MainAxisAlignment.spaceEvenly,
  children: [
    _buildButtonColumn(color, Icons.call, 'CALL'),
    _buildButtonColumn(color, Icons.near_me, 'ROUTE'),
    _buildButtonColumn(color, Icons.share, 'SHARE'),
  ],
);

添加按钮部分到 body 属性中去：

Add the button section to the body:

{step2 → step3}/lib/main.dart Viewed

@@ -48,3 +59,3 @@
     return MaterialApp(
       title: 'Flutter layout demo',
       home: Scaffold(
@@ -54,8 +65,9 @@
         body: Column(
           children: [
             titleSection,
+            buttonSection,
           ],
         ),
       ),
     );
   }

第四步: 实现文本区域

Step 4: Implement the text section

将文本区域定义为一个变量，将文本放置到一个 Container 容器中，然后为每条边添加内边距。只需在 buttonSection 声明下添加如下代码：

Define the text section as a variable. Put the text in a Container and add padding along each edge. Add the following code just below the buttonSection declaration:

Widget textSection = const Padding(
  padding: EdgeInsets.all(32),
  child: Text(
    'Lake Oeschinen lies at the foot of the Blüemlisalp in the Bernese '
    'Alps. Situated 1,578 meters above sea level, it is one of the '
    'larger Alpine Lakes. A gondola ride from Kandersteg, followed by a '
    'half-hour walk through pastures and pine forest, leads you to the '
    'lake, which warms to 20 degrees Celsius in the summer. Activities '
    'enjoyed here include rowing, and riding the summer toboggan run.',
    softWrap: true,
  ),
);

通过设置 softwrap 为 true，文本将在填充满列宽后在单词边界处自动换行。

By setting softwrap to true, text lines will fill the column width before wrapping at a word boundary.

添加文本部分到 body 属性：

Add the text section to the body:

{step3 → step4}/lib/main.dart Viewed

@@ -59,3 +72,3 @@
     return MaterialApp(
       title: 'Flutter layout demo',
       home: Scaffold(
@@ -66,6 +79,7 @@
           children: [
             titleSection,
             buttonSection,
+            textSection,
           ],
         ),
       ),

第五步: 实现图片区域

Step 5: Implement the image section

四个列元素中的三个已经完成了，只剩下图片部分了。如下添加图片文件到示例工程中：

Three of the four column elements are now complete, leaving only the image. Add the image file to the example:

Create an images directory at the top of the project.
添加 lake.jpg
Add lake.jpg.

更新 pubspec.yaml 文件，添加一个 assets 标签。这使得在你的代码中可以访问到该图片。
Update the pubspec.yaml file to include an assets tag. This makes the image available to your code.

{step4 → step5}/pubspec.yaml Viewed

@@ -18,3 +18,5 @@

18

18

flutter:

19

19

uses-material-design: true

20

+ assets:

21

+ - images/lake.jpg

现在你可以在你的代码中引用该图片了：

Now you can reference the image from your code:

{step4 → step5}/lib/main.dart Viewed

@@ -77,6 +77,12 @@
         ),
         body: Column(
           children: [
+            Image.asset(
+              'images/lake.jpg',
+              width: 600,
+              height: 240,
+              fit: BoxFit.cover,
+            ),
             titleSection,
             buttonSection,
             textSection,

BoxFit.cover 告诉系统图片应当尽可能等比缩小到刚好能够覆盖住整个渲染 box。

BoxFit.cover tells the framework that the image should be as small as possible but cover its entire render box.

第六步: 最终的收尾

Step 6: Final touch

在最后的步骤中，需要在一个 ListView 中排列好所有的元素，而不是在一个 Column 中，因为当 app 运行在某个小设备上时，ListView 支持 app body 的滚动。

In this final step, arrange all of the elements in a ListView, rather than a Column, because a ListView supports app body scrolling when the app is run on a small device.

{step5 → step6}/lib/main.dart Viewed

@@ -72,13 +77,13 @@
     return MaterialApp(
       title: 'Flutter layout demo',
       home: Scaffold(
         appBar: AppBar(
           title: const Text('Flutter layout demo'),
         ),
-        body: Column(
+        body: ListView(
           children: [
             Image.asset(
               'images/lake.jpg',
               width: 600,
               height: 240,
               fit: BoxFit.cover,

Dart code: main.dart
Image: images
Pubspec: pubspec.yaml

大功告成！当你热加载 app 时，你应当可以看到和本页开头截图一样的 app 布局了。

That’s it! When you hot reload the app, you should see the same app layout as the screenshot at the top of this page.

你可以参考文档为你的 Flutter 应用加入交互体验来给这个布局增加交互。

You can add interactivity to this layout by following Adding Interactivity to Your Flutter App.

创建响应式和自适应的应用

自适应应用和响应式应用的区别
The difference between an adaptive and a responsive app
构建一个响应式的 Flutter 应用
Creating a responsive Flutter app
- 更多资源
  Other resources
创建自适应的 Flutter 应用
Creating an adaptive Flutter app
- 更多资源
  Other resources

Flutter 的首要目标，是构建一个可以使用单一代码来源，开发在所有平台上都有着良好的视觉和体验的应用的框架。

One of Flutter’s primary goals is to create a framework that allows you to develop apps from a single codebase that look and feel great on any platform.

这意味着你的应用可能会在不同大小的屏幕上使用，从智能手表，到可折叠的双屏设备，再到高清显示器。

This means that your app may appear on screens of many different sizes, from a watch, to a foldable phone with two screens, to a high def monitor.

通常这样的考量被分为两种概念：自适应 和 响应式。理想条件下，你的应用应该两者兼具，但是它们究竟代表了什么？这两种概念有些类似，但并不是同一种含义。

Two terms that describe concepts for this scenario are adaptive and responsive. Ideally, you’d want your app to be both but what, exactly, does this mean? These terms are similar, but they are not the same.

自适应应用和响应式应用的区别

The difference between an adaptive and a responsive app

自适应 和 响应式 可以看作应用里的两种维度：你的应用可能是自适应的，但不是响应式的，又或是反行其道。当然，你的应用可能既自适应又为响应式，也可能两者均未实现。

Adaptive and responsive can be viewed as separate dimensions of an app: you can have an adaptive app that is not responsive, or vice versa. And, of course, an app can be both, or neither.

响应式
通常来说，一个 响应式 应用的布局会根据可用的屏幕大小而调整。常见的场景是在用户重新调整窗口大小或旋转屏幕时，重新布局 UI。对于需要在多种设备（手表、手机、平板、笔记本或台式机）上运行的应用而言，这是必要的要素。

Responsive
Typically, a responsive app has had its layout tuned for the available screen size. Often this means (for example), re-laying out the UI if the user resizes the window, or changes the device’s orientation. This is especially necessary when the same app can run on a variety of devices, from a watch, phone, tablet, to a laptop or desktop computer.

自适应
应用以 自适应 的方式在不同的设备上（移动端和桌面端）运行，需要同时处理鼠标、键盘和触控输入。这也意味着应用的视觉密度、组件的选择（层级菜单或底部抽屉）、平台特定的行为（例如置顶的窗口）等内容将在不同的平台上有一定的差异。

Adaptive
Adapting an app to run on different device types, such as mobile and desktop, requires dealing with mouse and keyboard input, as well as touch input. It also means there are different expectations about the app’s visual density, how component selection works (cascading menus vs bottom sheets, for example), using platform-specific features (such as top-level windows), and more.

构建一个响应式的 Flutter 应用

Creating a responsive Flutter app

Flutter 让你能够构建自动适配屏幕大小和旋转方向的应用。

Flutter allows you to create apps that self-adapt to the device’s screen size and orientation.

构建响应式设计的 Flutter 应用，有以下两种较为基础的方式：

There are two basic approaches to creating Flutter apps with responsive design:

使用 LayoutBuilder 类
通过它的 builder 属性，你可以得到一个 BoxConstraints 对象。你可以检查约束里的属性，来决定如何进行显示。例如，如果约束里的 maxWidth 超过了你的宽度分界点，你可以返回一个 Scaffold，它包含一列内容，左侧是一个列表。如果约束更小，则返回一个列表在抽屉里的 Scaffold。你也可以根据你的设备高度、屏幕的比例或者其他的属性，来调整你的显示。当约束改变时（例如用户旋转了手机，或是在 Android N 上将应用放置到 tile UI 中）构建方法会运行。

Use the LayoutBuilder class
From its builder property, you get a BoxConstraints object. Examine the constraint’s properties to decide what to display. For example, if your maxWidth is greater than your width breakpoint, return a Scaffold object with a row that has a list on the left. If it’s narrower, return a Scaffold object with a drawer containing that list. You can also adjust your display based on the device’s height, the aspect ratio, or some other property. When the constraints change (for example, the user rotates the phone, or puts your app into a tile UI in Nougat), the build function runs.

在构建方法中使用 MediaQuery.of() 方法
这个方法可以获取到当前应用（基于上下文）的尺寸、旋转方向等信息。如果你需要基于完整的上下文信息进行布局决策，而不是基于特定的 widget，这个方法将非常有用。同样的，如果应用的尺寸发生了改变，构建方法也会自动执行。

Use the MediaQuery.of() method in your build functions
This gives you the size, orientation, etc, of your current app. This is more useful if you want to make decisions based on the complete context rather than on just the size of your particular widget. Again, if you use this, then your build function automatically runs if the user somehow changes the app’s size.

以下是其他有助于构建响应式界面的 widget：

Other useful widgets and classes for creating a responsive UI:

Other resources

想了解更多信息，以下是一些来自社区贡献的资源：

For more information, here are a few resources, including contributions from the Flutter community:

使用 Flutter 开发兼顾多种屏幕尺寸和旋转的应用，由 Deven Joshi 撰写
Developing for Multiple Screen Sizes and Orientations in Flutter by Deven Joshi
使用 Flutter 构建响应式界面，由 Raouf Rahiche 撰写
Build Responsive UIs in Flutter by Raouf Rahiche
构建响应式的 Flutter 跨平台的登录页，由 Priyanka Tyagi 撰写
Making Cross-platform Flutter Landing Page Responsive by Priyanka Tyagi
如何根据不同的屏幕大小构建响应式的 Flutter 应用？，在 StackOverflow 上的一个问题。
How to make flutter app responsive according to different screen size?, a question on StackOverflow

创建自适应的 Flutter 应用

Creating an adaptive Flutter app

你可以阅读由 gskinner 团队撰写的构建自适应的应用了解更多关于构建自适应应用的内容。

Learn more about creating an adaptive Flutter app with Building adaptive apps, written by the gskinner team.

你也可以观看下面几期关于自适应布局的 The Boring Show：

You might also check out the following episodes of The Boring Show:

Adaptive layouts

Adaptive layouts, part 2

想要尝试精美的自适应应用，可以下载由 gskinner 和 Flutter 团队共建的剪贴板应用 Flutter Folio：

For an excellent example of an adaptive app, check out Flutter Folio, a scrapbooking app created in collaboration with gskinner and the Flutter team:

Folio 应用的源代码也可以在 GitHub 找到，你可以阅读 gskinner 的博客了解更多内容。

The Folio source code is also available on GitHub. Learn more on the gskinner blog.

Other resources

你可以在以下的资源中了解更多关于如何构建自适应平台应用的内容：

You can learn more about creating platform adaptive apps in the following resources:

不同平台操作体验的差异和适配，站内的另一篇文档。
Platform-specific behaviors and adaptations, a page on this site.
设计真正能够自适应的用户交互，由 Aloïs Deniel 在今年的 FlutterViking 会议上发布的文章和视频。
Designing truly adaptive user interfaces a blog post and video by Aloïs Deniel, presented at this year’s FlutterViking conference.
以自适应应用为目标编写的 Flutter Gallery 应用（源代码仓库）。
The Flutter gallery app (repo) has been written as an adaptive app.

构建自适应的应用

概览
Overview
构建自适应的布局
Building adaptive layouts
输入
Input
平台行为习惯与规范
Idioms and norms

概览

Overview

Flutter 为在移动端、桌面端和 Web 端使用同样的代码构建应用创造了新的机会。伴随着机会而来的，是新的挑战。你可能会希望你的应用既能在尽可能复用的情况下自适应多个平台，又能保证流畅且无缝的体验，还可以让用户保持一致的使用习惯。这样的应用不仅仅是为了多个平台而构建的，它能完全地自适应平台的变化。

Flutter provides new opportunities to build apps that can run on mobile, desktop, and the web from a single codebase. However, with these opportunities, come new challenges. You want your app to feel familiar to users, adapting to each platform by maximizing usability and ensuring a comfortable and seamless experience. That is, you need to build apps that are not just multiplatform, but are fully platform adaptive.

在构建平台自适应的应用时，有众多的考量因素，总的来说分为以下几类：

There are many considerations for developing platform-adaptive apps, but they fall into three major categories:

布局
Layout
输入
Input
平台行为习惯与规范
Idioms and norms

指南将通过代码片段，详细说明三个类别的概念。若你想了解这些概念的实际落地情况，可以参考 Flokk 和 Folio 示例。

This page covers all three categories in detail using code snippets to illustrate the concepts. If you’d like to see how these concepts come together, check out the Flokk and Folio examples that were built using the concepts described here.

Original demo code for adaptive app development techniques from flutter-adaptive-demo.

构建自适应的布局

Building adaptive layouts

在构建多平台的应用时，首要考虑的是如何针对不同大小的设备进行尺寸适配。

One of the first things you must consider when bringing your app to multiple platforms is how to adapt it to the various sizes and shapes of the screens that it will run on.

布局 widgets

Layout widgets

如果你已经开发过应用或网站，那你可能已经熟悉如何构建自适应的界面。好消息是，对于 Flutter 开发者而言，有非常多的 widgets 让构建更为简单。

If you’ve been building apps or websites, you’re probably familiar with creating responsive interfaces. Luckily for Flutter developers, there are a large set of widgets to make this easier.

Flutter 中最有用的部分布局 widgets 包括：

Some of Flutter’s most useful layout widgets include:

单子级 (Single child)

Single child

Align——让子级在其内部进行对齐。可使用 -1 至 1 之间的任意值在垂直和水平方向上进行对齐。
Align—Aligns a child within itself. It takes a double value between -1 and 1, for both the vertical and horizontal alignment.
AspectRatio——尝试让子级以指定的比例进行布局。
AspectRatio—Attempts to size the child to a specific aspect ratio.
ConstrainedBox——对子级施加尺寸限制，可以控制最小和最大的尺寸。
ConstrainedBox—Imposes size constraints on its child, offering control over the minimum or maximum size.
CustomSingleChildLayout——使用代理方法对单个子级进行定位。代理方法可以为子级确定布局限制和定位。
CustomSingleChildLayout—Uses a delegate function to position a single child. The delegate can determine the layout constraints and positioning for the child.
Expanded 和 Flexible——允许 Row 或 Column 的子级填充剩余空间或者尽可能地小。
Expanded and Flexible—Allows a child of a Row or Column to shrink or grow to fill any available space.
FractionallySizedBox——基于剩余空间的比例限定子级的大小。
FractionallySizedBox—Sizes its child to a fraction of the available space.
LayoutBuilder——让子级可以基于父级的尺寸重新调整其布局。
LayoutBuilder—Builds a widget that can reflow itself based on its parents size.
SingleChildScrollView——为单一的子级添加滚动。通常配合 Row 或 Column 进行使用。
SingleChildScrollView—Adds scrolling to a single child. Often used with a Row or Column.

多子级 (Multi child)

Multichild

Column、Row 和 Flex—— 在同一水平线或垂直线上放置所有子级。 Column 和 Row 都继承了 Flex widget。
Column, Row, and Flex—Lays out children in a single horizontal or vertical run. Both Column and Row extend the Flex widget.
CustomMultiChildLayout—— 在布局过程中使用代理方法对多个子级进行定位。
CustomMultiChildLayout—Uses a delegate function to position multiple children during the layout phase.
Flow——相对于 CustomMultiChildLayout 更高效的布局方式。在绘制过程中使用代理方法对多个子级进行定位。
Flow—Similar to CustomMultiChildLayout, but more efficient because it’s performed during the paint phase rather than the layout phase.
ListView、GridView 和 CustomScrollView—— 为所有子级增加滚动支持。
ListView, GridView, and CustomScrollView—Provides scrollable lists of children.
Stack——基于 Stack 的边界对多个子级进行放置和定位。与 CSS 中的 position: fixed 功能类似。
Stack—Layers and positions multiple children relative to the edges of the Stack. Functions similarly to position-fixed in CSS.
Table——使用经典的表格布局算法，可以组合多列和多行。
Table—Uses a classic table layout algorithm for its children, combining multiple rows and columns.
Wrap——将子级顺序显示在多行或多列内。
Wrap—Displays its children in multiple horizontal or vertical runs.

查看布局 widgets 了解更多的 widgets 和代码示例。

To see more available widgets and example code, see Layout widgets.

视觉密度

Visual density

不同的设备会提供不同级别的显示密度，使得操作的命中区域也要随之变化。 Flutter 的 VisualDensity 类可以让你快速地调整整个应用的视图密度，比如在可触控设备上放大一个按钮（使其更容易被点击）。

Different input devices offer various levels of precision, which necessitate differently sized hit areas. Flutter’s VisualDensity class makes it easy to adjust the density of your views across the entire application, for example, by making a button larger (and therefore easier to tap) on a touch device.

在你改变 MaterialApp 的 VisualDensity 时，已支持 VisualDensity 的 MaterialComponents 会以动画过渡的形式改变其自身的密度。水平和垂直方向的密度默认都为 0.0，你可以将它设置为任意的正负值，这样就可以通过调整密度轻松地调整你的 UI：

When you change the VisualDensity for your MaterialApp, MaterialComponents that support it animate their densities to match. By default, both horizontal and vertical densities are set to 0.0, but you can set the densities to any negative or positive value that you want. By switching between different densities, you can easily adjust your UI:

Adaptive scaffold

若想使用自定义的视觉密度，请在你的 MaterialApp 的主题中进行设置：

To set a custom visual density, inject the density into your MaterialApp theme:

double densityAmt = touchMode ? 0.0 : -1.0;
VisualDensity density =
    VisualDensity(horizontal: densityAmt, vertical: densityAmt);
return MaterialApp(
  theme: ThemeData(visualDensity: density),
  home: MainAppScaffold(),
  debugShowCheckedModeBanner: false,
);

若想在你的视图中使用 VisualDensity，你可以向上查找：

To use VisualDensity inside your own views, you can look it up:

VisualDensity density = Theme.of(context).visualDensity;

在密度变化时，容器不仅能自动地对其做出反应，还会结合动画进行过渡变化。所有的组件都会联系在一起，使整个应用平滑过渡。

Not only does the container react automatically to changes in density, it also animates when it changes. This ties together your custom components, along with the built-in components, for a smooth transition effect across the app.

我们可以看到，VisualDensity 是没有单位的，所以在不同的视图上可能有不同的含义。在以上的例子中，1 个单位的密度等同于 6 个逻辑像素。具体的处理完全由你的视图自行决定。无单位的设计让它可以处理通用情况，能在大部分的场景下使用。

As shown, VisualDensity is unit-less, so it can mean different things to different views. In this example, 1 density unit equals 6 pixels, but this is totally up to your views to decide. The fact that it is unit-less makes it quite versatile, and it should work in most contexts.

值得注意的是，在 Material 的组件中，1 个单位的视觉密度通常等于 4 个逻辑像素。你可以查看 VisualDensity API 文档了解更多支持视觉密度的组件。若想了解视觉密度的通用原则，请查看 Material Design 指南。

It’s worth noting that the Material Components generally use a value of around 4 logical pixels for each visual density unit. For more information about the supported components, see VisualDensity API. For more information about density principles in general, see the Material Design guide.

基于上下文的布局

Contextual layout

如果你需要的不仅是密度的变化，并且没有找到一个满足需求的 widget，那么你可以使用代码进行更细化的控制、计算尺寸、切换 widgets 或是完全重新构建你的 UI 适配对应的外形结构。

If you need more than density changes and can’t find a widget that does what you need, you can take a more procedural approach to adjust parameters, calculate sizes, swap widgets, or completely restructure your UI to suit a particular form factor.

基于屏幕大小的分界点

Screen-based breakpoints

最简单的代码控制布局方式是基于屏幕尺寸来定义分界点。在 Flutter 中，你可以使用 MediaQuery API 实现这些分界点。具体需要使用的大小并没有作出硬性规定，下方是一些通用的值：

The simplest form of procedural layouts uses screen-based breakpoints. In Flutter, this can be done with the MediaQuery API. There are no hard and fast rules for the sizes to use here, but these are general values:

class FormFactor {
  static double desktop = 900;
  static double tablet = 600;
  static double handset = 300;
}

使用分界点可以让你通过简单的判断快速确定设备的类型：

Using breakpoints, you can set up a simple system to determine the device type:

ScreenType getFormFactor(BuildContext context) {
  // Use .shortestSide to detect device type regardless of orientation
  double deviceWidth = MediaQuery.of(context).size.shortestSide;
  if (deviceWidth > FormFactor.desktop) return ScreenType.Desktop;
  if (deviceWidth > FormFactor.tablet) return ScreenType.Tablet;
  if (deviceWidth > FormFactor.handset) return ScreenType.Handset;
  return ScreenType.Watch;
}

又或者，你可以对大小类型进行更深层次的抽象，并且按照从小到大的方式定义：

As an alternative, you could abstract it more and define it in terms of small to large:

enum ScreenSize { Small, Normal, Large, ExtraLarge }

ScreenSize getSize(BuildContext context) {
  double deviceWidth = MediaQuery.of(context).size.shortestSide;
  if (deviceWidth > 900) return ScreenSize.ExtraLarge;
  if (deviceWidth > 600) return ScreenSize.Large;
  if (deviceWidth > 300) return ScreenSize.Normal;
  return ScreenSize.Small;
}

使用基于屏幕大小的分界点的最佳场景，是在应用的顶层进行尺寸决策。在需要改变视觉密度、边距或者字体大小时，定义全局的基数是最好的方式。

Screen-based breakpoints are best used for making top-level decisions in your app. Changing things like visual density, paddings, or font-sizes are best when defined on a global basis.

你也可以利用分界点重新组织顶层的 widget 结构。例如，你可以判断用户是否使用手持设备，来切换垂直或水平的布局：

You can also use screen-based breakpoints to reflow your top-level widget trees. For example, you could switch from a vertical to a horizontal layout when the user isn’t on a handset:

bool isHandset = MediaQuery.of(context).size.width < 600;
return Flex(
    children: [Text("Foo"), Text("Bar"), Text("Baz")],
    direction: isHandset ? Axis.vertical : Axis.horizontal);

在其他的 widget 中，你也可以切换部分子级 widget：

In another widget, you might swap some of the children completely:

Widget foo = Row(
  children: [
    ...isHandset ? _getHandsetChildren() : _getNormalChildren(),
  ],
);

使用 LayoutBuilder 提升布局灵活性

Use LayoutBuilder for extra flexibility

尽管对于全屏页面或者全局的布局决策而言，判断整个屏幕大小非常有效，但对于内嵌的子视图而言，并不一定是合理的方案。子视图通常有自己的分界点，并且只关心它们可用的渲染空间。

Even though checking total screen size is great for full-screen pages or making global layout decisions, it’s often not ideal for nested subviews. Often, subviews have their own internal breakpoints and care only about the space that they have available to render.

在 Flutter 内处理这类场景最简单的做法是使用 LayoutBuilder。 LayoutBuilder 让 widget 可以根据其父级的限制进行调整，相比依赖全局的尺寸限制而言更为通用。

The simplest way to handle this in Flutter is using the LayoutBuilder class. LayoutBuilder allows a widget to respond to incoming local size constraints, which can make the widget more versatile than if it depended on a global value.

之前的示例可以使用 LayoutBuilder 重写：

The previous example could be rewritten using LayoutBuilder:

Widget foo = LayoutBuilder(
    builder: (BuildContext context, BoxConstraints constraints) {
  bool useVerticalLayout = constraints.maxWidth < 400.0;
  return Flex(
    children: [
      Text("Hello"),
      Text("World"),
    ],
    direction: useVerticalLayout ? Axis.vertical : Axis.horizontal,
  );
});

现在这个 widget 可以组装在侧边面板、弹框又或是全屏视图中，并且根据尺寸自适应布局。

This widget can now be composed within a side panel, dialog, or even a full-screen view, and adapt its layout to whatever space is provided.

设备细分

Device segmentation

有时你可能需要根据实际运行的平台进行布局处理，而不是基于大小。例如，在构建自定义的标题栏时，你可能需要判断设备的平台来处理布局，以防被原生窗口的按钮遮挡。

There are times when you want to make layout decisions based on the actual platform you’re running on, regardless of size. For example, when building a custom title bar, you might need to check the operating system type and tweak the layout of your title bar, so it doesn’t get covered by the native window buttons.

想判断应用当前所处的平台，你可以使用 Platform API 和 kIsWeb 组合进行判断：

To determine which combination of platforms you’re on, you can use the Platform API along with the kIsWeb value:

bool get isMobileDevice => !kIsWeb && (Platform.isIOS || Platform.isAndroid);
bool get isDesktopDevice =>
    !kIsWeb && (Platform.isMacOS || Platform.isWindows || Platform.isLinux);
bool get isMobileDeviceOrWeb => kIsWeb || isMobileDevice;
bool get isDesktopDeviceOrWeb => kIsWeb || isDesktopDevice;

在构建 Web 平台应用时，由于 dart.io package 不支持 Web 平台，导致使用 Platform API 时会异常。所以在上面的代码中，会首先判断是否在 Web 平台，基于这个条件，在 Web 平台上永远不会调用 Platform API。

The Platform API can’t be accessed from web builds without throwing an exception, because the dart.io package is not supported on the web target. As a result, this code checks for web first, and because of short-circuiting, Dart will never call Platform on web targets.

使用单一来源控制样式

Single source of truth for styling

使用单一的来源对样式进行维护，可以让你更简便地控制边距、间距、圆角、字体等样式值。你可以利用一些帮助类进行实现：

You’ll probably find it easier to maintain your views if you create a single source of truth for styling values like padding, spacing, corner shape, font sizes, and so on. This can be done easily with some helper classes:

class Insets {
  static const double xsmall = 3;
  static const double small = 4;
  static const double medium = 5;
  static const double large = 10;
  static const double extraLarge = 20;
  // etc
}

class Fonts {
  static const String raleway = 'Raleway';
  // etc
}

class TextStyles {
  static const TextStyle raleway = const TextStyle(
    fontFamily: Fonts.raleway,
  );
  static TextStyle buttonText1 =
      TextStyle(fontWeight: FontWeight.bold, fontSize: 14);
  static TextStyle buttonText2 =
      TextStyle(fontWeight: FontWeight.normal, fontSize: 11);
  static TextStyle h1 = TextStyle(fontWeight: FontWeight.bold, fontSize: 22);
  static TextStyle h2 = TextStyle(fontWeight: FontWeight.bold, fontSize: 16);
  static late TextStyle body1 = raleway.copyWith(color: Color(0xFF42A5F5));
  // etc
}

这些常量可以用来替代硬编码的值：

These constants can then be used in place of hard-coded numeric values:

return Padding(
  padding: EdgeInsets.all(Insets.small),
  child: Text('Hello!', style: TextStyles.body1),
);

由于所有的视图都引用了相同设计系统的规范，它们通常看起来更一致且更顺畅。与其进行容易出错的搜索替换，你可以将平台对应样式值的修改集中在一处。使用共享的规则也对设计的一致性有所帮助。

With all views referencing the same shared-design system rules, they tend to look better and more consistent. Making a change or adjusting a value for a specific platform can be done in a single place, instead of using an error-prone search and replace. Using shared rules has the added benefit of helping enforce consistency on the design side.

常见的设计类型里，如下这些类别可以以这样的方式进行组织：

Some common design system categories that can be represented this way are:

动画时间
Animation timings
尺寸大小和分界点
Sizes and breakpoints
遮盖和内边距区域
Insets and paddings
圆角
Corner radius
阴影
Shadows
笔画
Strokes
字体系列、大小和样式
Font families, sizes, and styles

当然，上述的例子也有一些例外：在应用中只使用了一次的值。将这些值放在样式规则里属实无用之举，但可以考虑它们是否能从现有的值延伸（例如 padding + 1.0）。你也可以留意一些有着相同意义复用的值，这些值也许可以添加到全局的样式规则里。

Like most rules, there are exceptions: one-off values that are used nowhere else in the app. There is little point in cluttering up the styling rules with these values, but it’s worth considering if they should be derived from an existing value (for example, padding + 1.0). You should also watch for reuse or duplication of the same semantic values. Those values should likely be added to the global styling ruleset.

针对不同外形屏幕的特性进行设计

Design to the strengths of each form factor

除了屏幕尺寸以外，你也应当花时间，针对各种不同外形屏幕的优劣点进行设计。支持多平台的应用，并不能在所有的设备上都提供理想的体验。实际开发时，可以考虑某些特定的功能是否合理，也可以考虑在某些平台上移除特定的功能。

Beyond screen size, you should also spend time considering the unique strengths and weaknesses of different form factors. It isn’t always ideal for your multiplatform app to offer identical functionality everywhere. Consider whether it makes sense to focus on specific capabilities, or even remove certain features, on some device categories.

举个例子，移动设备是十分便携的，一般还配有摄像头，但它们并不适合深度的内容创作工作。基于这个前提，你的应用可以更侧重于内容捕获，并使用位置信息对其进行标记，配上移动端的界面，而另一方面，在平板和桌面界面上专注于组织和操作产出的内容。

For example, mobile devices are portable and have cameras, but they aren’t well suited for detailed creative work. With this in mind, you might focus more on capturing content and tagging it with location data for a mobile UI, but focus on organizing or manipulating that content for a tablet or desktop UI.

另一个例子是充分利用 Web 平台的快速分享能力。如果你正在部署 Web 应用，可以考虑哪些页面会使用 deep link，并根据配置来设计应用的导航。

Another example is leveraging the web’s extremely low barrier for sharing. If you’re deploying a web app, decide which deep links to support, and design your navigation routes with those in mind.

此处的关键点在于，如何发挥每个平台的长处，寻找平台可以利用的特有功能。

The key takeaway here is to think about what each platform does best and see if there are unique capabilities you can leverage.

通过构建桌面应用程序进行快速测试

Use desktop build targets for rapid testing

测试自适应界面的最快方式，是利用桌面端快速进行构建。

One of the most effective ways to test adaptive interfaces is to take advantage of the desktop build targets.

在桌面上运行应用时，你可以在应用运行时轻易地改变窗口的大小，预览多种尺寸的布局。配上热重载，能极大程度地加快响应式开发的速度。

When running on a desktop, you can easily resize the window while the app is running to preview various screen sizes. This, combined with hot reload, can greatly accelerate the development of a responsive UI.

Adaptive scaffold 2

优先处理触摸操作

Solve touch first

在移动端构建优良的触摸交互式 UI 通常比传统的桌面端更为困难，因为它缺少类似右键单击、滚轮或键盘快捷键这样的快速输入设备。

Building a great touch UI can often be more difficult than a traditional desktop UI due, in part, to the lack of input accelerators like right-click, scroll wheel, or keyboard shortcuts.

在一开始就专注于提升触摸体验的 UI，足以应对这样的挑战。你依旧可以使用桌面端来提高你的开发效率，但要记得时不时切换回移动端，验证开发的内容是否正常。

One way to approach this challenge is to focus initially on a great touch-oriented UI. You can still do most of your testing using the desktop target for its iteration speed. But, remember to switch frequently to a mobile device to verify that everything feels right.

完善了触摸界面后，你可以调整面向鼠标用户的视觉密度，然后对所有的输入设备进行分层。这些输入设备应当作为加快你的应用使用速度的途径。在这里需要考虑的应当是用户对于应用体验的期望，并在应用中合理地实现这些期望。

After you have the touch interface polished, you can tweak the visual density for mouse users, and then layer on all the additional inputs. Approach these other inputs as accelerator—alternatives that make a task faster. The important thing to consider is what a user expects when using a particular input device, and work to reflect that in your app.

输入

Input

当然，应用只适配了界面是远远不够的，你还需要适配各种用户的输入操作。鼠标和键盘提供了触摸设备不具备的输入方式，例如滚轮、右键点击、悬停交互、Tab 遍历切换和键盘快捷键。

Of course, it isn’t enough to just adapt how your app looks, you also have to support varying user inputs. The mouse and keyboard introduce input types beyond those found on a touch device—like scroll wheel, right-click, hover interactions, tab traversal, and keyboard shortcuts.

滚轮

Scroll wheel

像 ScrollView 和 ListView 这样的滚动 widget 默认支持滚轮行为，而大部分可滚动的自定义 widget 都是基于它们构建的，所以也同样支持。

Scrolling widgets like ScrollView or ListView support the scroll wheel by default, and because almost every scrollable custom widget is built using one of these, it works with them as well.

如果你需要实现自定义的滑动行为，可以使用 Listener widget，通过它你可以完全自定义 UI 如何响应滚轮行为。

If you need to implement custom scroll behavior, you can use the Listener widget, which lets you customize how your UI reacts to the scroll wheel.

return Listener(
    onPointerSignal: (event) {
      if (event is PointerScrollEvent) print(event.scrollDelta.dy);
    },
    child: ListView());

Tab 遍历切换和焦点交互

Tab traversal and focus interactions

使用键盘的用户，可能会希望通过 Tab 键在应用中快速导航，特别是对有动效和视觉障碍的用户，他们几乎完全依赖于键盘导航。

Users with physical keyboards expect that they can use the tab key to quickly navigate your application, and users with motor or vision differences often rely completely on keyboard navigation.

在考虑 Tab 遍历切换时，有两点需要注意：焦点如何在 widget 之间遍历，以及 widget 聚焦时的突出显示。

There are two considerations for tab interactions: how focus moves from widget to widget, known as traversal, and the visual highlight shown when a widget is focused.

大部分内置的组件，类似于按钮和输入框，都默认支持遍历和高亮。如果你想让自己的 widget 包含在遍历中，你可以利用 FocusableActionDetector 进行控制。它将 Actions、Shortcuts、MouseRegion 和 Focus 的能力进行了整合，创建出一个可以定义行为和键位绑定，并且提供聚焦和悬浮高亮事件回调的 widget。

Most built-in components, like buttons and text fields, support traversal and highlights by default. If you have your own widget that you want included in traversal, you can use the FocusableActionDetector widget to create your own controls. It combines the functionality of Actions, Shortcuts, MouseRegion, and Focus widgets to create a detector that defines actions and key bindings, and provides callbacks for handling focus and hover highlights.

class _BasicActionDetectorState extends State<BasicActionDetector> {
  bool _hasFocus = false;
  @override
  Widget build(BuildContext context) {
    return FocusableActionDetector(
      onFocusChange: (value) => setState(() => _hasFocus = value),
      actions: <Type, Action<Intent>>{
        ActivateIntent: CallbackAction<Intent>(onInvoke: (Intent intent) {
          print("Enter or Space was pressed!");
        }),
      },
      child: Stack(
        clipBehavior: Clip.none,
        children: [
          FlutterLogo(size: 100),
          // Position focus in the negative margin for a cool effect
          if (_hasFocus)
            Positioned(
                left: -4,
                top: -4,
                bottom: -4,
                right: -4,
                child: _roundedBorder())
        ],
      ),
    );
  }
}

控制遍历的顺序

Controlling traversal order

想要控制用户按下 Tab 键时的 widget 切换顺序，你可以使用 FocusTraversalGroup 来指定树中的区域，作为切换时的组别。

To get more control over the order that widgets are focused on when the user presses tab, you can use FocusTraversalGroup to define sections of the tree that should be treated as a group when tabbing.

例如，你可能想要用户逐个切换所有的输入框，最后再切换到提交按钮：

For example, you might to tab through all the fields in a form before tabbing to the submit button:

return Column(children: [
  FocusTraversalGroup(
    child: MyFormWithMultipleColumnsAndRows(),
  ),
  SubmitButton(),
]);

Flutter 有几种内置的方法对 widget 和组别进行遍历，默认使用的是 ReadingOrderTraversalPolicy 类。这个类通常可以正常使用，你也可以创建另一个 TraversalPolicy 或创建一个自定义的规则，对它进行定义。

Flutter has several built-in ways to traverse widgets and groups, defaulting to the ReadingOrderTraversalPolicy class. This class usually works well, but it’s possible to modify this using another predefined TraversalPolicy class or by creating a custom policy.

提升用户操作速度的键盘

Keyboard accelerators

除了使用 Tab 遍历元素以外，桌面和 Web 用户还习惯将为各种操作绑定键盘快捷键。无论是 Delete 键进行快速删除，还是 Control+N 新建文档，你都需要认真考虑用户对这些操作的期望。键盘是非常强力的输入工具，所以请尽可能让它发挥最大的作用和效果。用户会给予高度评价。

In addition to tab traversal, desktop and web users are accustomed to having various keyboard shortcuts bound to specific actions. Whether it’s the Delete key for quick deletions or Control+N for a new document, be sure to consider the different accelerators your users expect. The keyboard is a powerful input tool, so try to squeeze as much efficiency from it as you can. Your users will appreciate it!

根据目标的不同，在 Flutter 中可以通过几种方式实现利用键盘提升用户操作速度。

Keyboard accelerators can be accomplished in a few ways in Flutter depending on your goals.

如果你已经有一个包含焦点的 widget，例如 TextField 或者 Button，你可以嵌套一个 RawKeyboardListener 监听键盘事件：

If you have a single widget like a TextField or a Button that already has a focus node, you can wrap it in a RawKeyboardListener and listen for keyboard events:

  @override
  Widget build(BuildContext context) {
    return Focus(
      onKey: (FocusNode node, RawKeyEvent event) {
        if (event is RawKeyDownEvent) {
          print(event.logicalKey);
        }
        return KeyEventResult.ignored;
      },
      child: ConstrainedBox(
        constraints: BoxConstraints(maxWidth: 400),
        child: TextField(
          decoration: InputDecoration(
            border: OutlineInputBorder(),
          ),
        ),
      ),
    );
  }
}

如果你想将一组键盘快捷键应用到更大范围的 widget，你可以使用 Shortcuts widget：

If you’d like to apply a set of keyboard shortcuts to a large section of the tree, you can use the Shortcuts widget:

// Define a class for each type of shortcut action you want
class CreateNewItemIntent extends Intent {
  const CreateNewItemIntent();
}

Widget build(BuildContext context) {
  return Shortcuts(
    // Bind intents to key combinations
    shortcuts: <ShortcutActivator, Intent>{
      SingleActivator(LogicalKeyboardKey.keyN, control: true):
          CreateNewItemIntent(),
    },
    child: Actions(
      // Bind intents to an actual method in your code
      actions: <Type, Action<Intent>>{
        CreateNewItemIntent: CallbackAction<CreateNewItemIntent>(
            onInvoke: (CreateNewItemIntent intent) => _createNewItem()),
      },
      // Your sub-tree must be wrapped in a focusNode, so it can take focus.
      child: Focus(
        autofocus: true,
        child: Container(),
      ),
    ),
  );
}

Shortcuts widget 非常有用，因为它会让 widget 树的这一分支或它的子级仅在有焦点且可见时触发快捷方式。

The Shortcuts widget is useful because it only allows shortcuts to be fired when this widget tree or one of its children has focus and is visible.

最后，你还可以全局添加监听。这样的监听可以用于始终需要监听，且为应用全局的快捷键，或是在任何时候（无论是否已聚焦）都接收快捷键的部分。使用 RawKeyboard 添加全局监听非常简单：

The final option is a global listener. This listener can be used for always-on, app-wide shortcuts or for panels that can accept shortcuts whenever they’re visible (regardless of their focus state). Adding global listeners is easy with RawKeyboard:

void initState() {
  super.initState();
  RawKeyboard.instance.addListener(_handleKey);
}

@override
void dispose() {
  RawKeyboard.instance.removeListener(_handleKey);
  super.dispose();
}

要想在全局监听中判断组合按键，你可以使用 RawKeyboard.instance.keysPressed 这个 Map 进行判断。例如下面这个方法，可以判断是否已经按下了指定的按键：

To check key combinations with the global listener, you can use the RawKeyboard.instance.keysPressed map. For example, a method like the following can check whether any of the provided keys are being held down:

static bool isKeyDown(Set<LogicalKeyboardKey> keys) {
  return keys.intersection(RawKeyboard.instance.keysPressed).isNotEmpty;
}

将它们合并判断，你就可以在 Shift+N 同时按下时触发行为：

Putting these two things together, you can fire an action when Shift+N is pressed:

void _handleKey(event) {
  if (event is RawKeyDownEvent) {
    bool isShiftDown = isKeyDown({
      LogicalKeyboardKey.shiftLeft,
      LogicalKeyboardKey.shiftRight,
    });
    if (isShiftDown && event.logicalKey == LogicalKeyboardKey.keyN) {
      _createNewItem();
    }
  }
}

使用静态的监听时有一件值得注意的事情，当用户在输入框中输入内容，或关联的 widget 从视图中隐藏时，通常需要禁用监听。与 Shortcuts 和 RawKeyboardListener 不同，你需要自己对它们进行管理。当你在为 Delete 键构建一个删除或退格行为的监听时，需要尤其注意，因为用户可能会在 TextField 中输入内容时受到影响。

One note of caution when using the static listener, is that you often need to disable it when the user is typing in a field or when the widget it’s associated with is hidden from view. Unlike with Shortcuts or RawKeyboardListener, this is your responsibility to manage. This can be especially important when you’re binding a Delete/Backspace accelerator for Delete, but then have child TextFields that the user might be typing in.

鼠标进入、移出和悬停事件

Mouse enter, exit, and hover

在桌面平台上，常会在鼠标悬停在内容上时，改变光标以表明不同的功能用途。例如，你会在鼠标悬停的按钮上看到手指光标，或是在悬停的文字上看到一个 I。

On desktop, it’s common to change the mouse cursor to indicate the functionality about the content the mouse is hovering over. For example, you usually see a hand cursor when you hover over a button, or an I cursor when you hover over text.

Material 系列组件内置了对标准的按钮和文字的光标支持。你可以使用 MouseRegion 在你自己的 widget 上改变光标。

The Material Component set has built-in support for your standard button and text cursors. To change the cursor from within your own widgets, use MouseRegion:

// Show hand cursor
return MouseRegion(
  cursor: SystemMouseCursors.click,
  // Request focus when clicked
  child: GestureDetector(
    onTap: () {
      Focus.of(context).requestFocus();
      _submit();
    },
    child: Logo(showBorder: hasFocus),
  ),
);

MouseRegion 对于创建自定义翻转和悬停效果也很有用：

MouseRegion is also useful for creating custom rollover and hover effects:

return MouseRegion(
  onEnter: (_) => setState(() => _isMouseOver = true),
  onExit: (_) => setState(() => _isMouseOver = false),
  onHover: (PointerHoverEvent e) => print(e.localPosition),
  child: Container(
    height: 500,
    color: _isMouseOver ? Colors.blue : Colors.black,
  ),
);

平台行为习惯与规范

Idioms and norms

最后，我们需要为自适应应用考虑平台标准。每个平台都有其不同的行为习惯与规范，这些名义和事实上的标准将操作应用的方法告知了用户。在当下网络如此便利的时代，用户更倾向于更加个性化的体验，但是提供这些平台标准，依然可以带来一些显著的好处：

The final area to consider for adaptive apps is platform standards. Each platform has its own idioms and norms; these nominal or de facto standards inform user expectations of how an application should behave. Thanks, in part to the web, users are accustomed to more customized experiences, but reflecting these platform standards can still provide significant benefits:

减少认知学习成本——与用户期望的交互进行匹配，让用户更直接地完成操作，而无需过多地思考，从而提高生产力，减少其中的顿挫感。
Reduce cognitive load—By matching the user’s existing mental model, accomplishing tasks becomes intuitive, which requires less thinking, boosts productivity, and reduces frustrations.
建立与用户之间的信任——在应用的交互表现不如预期时，用户会逐渐对应用本身产生怀疑。相反，使用让用户感到熟悉的 UI，可以快速地建立应用与用户之间的信任，让用户提高对应用质量的评价。同时这也会让应用商店的评级更为可观——皆大欢喜。
Build trust—Users can become wary or suspicious when applications don’t adhere to their expectations. Conversely, a UI that feels familiar can build user trust and can help improve the perception of quality. This often has the added benefit of better app store ratings—something we can all appreciate!

考虑每个平台的预期交互行为

Consider expected behavior on each platform

考虑的第一步，是花一些时间思考应用在这个平台上期望的外观、表现或者行为。试着将当前能否实现的限制抛诸脑后，仅针对理想的用户体验进行逆向思考。

The first step is to spend some time considering what the expected appearance, presentation, or behavior is on this platform. Try to forget any limitations of your current implementation, and just envision the ideal user experience. Work backwards from there.

另一种思考方式，是向自己提问：「该平台的用户要想完成这个操作，需要什么样的交互？」接着开始设想如何在应用内正常且无妥协地实现它。

Another way to think about this is to ask, “How would a user of this platform expect to achieve this goal?” Then, try to envision how that would work in your app without any compromises.

如果你本身不是这个平台的常用用户，这项工作就有一定的难度。某些特定的行为和习惯，很容易会被你完全忽略。例如，一位一直使用 Android 的用户很有可能不清楚 iOS 平台的约定，同样还有 macOS、Linux 和 Windows。对于身为开发者的你来说，这些差异可能微乎其微，但对于有经验的用户来说是显而易见的。

This can be difficult if you aren’t a regular user of the platform. You might be unaware of the specific idioms and can easily miss them completely. For example, a lifetime Android user will likely be unaware of platform conventions on iOS, and the same holds true for macOS, Linux, and Windows. These differences might be subtle to you, but be painfully obvious to an experienced user.

寻找一位平台的实际用户（倡导者）

Find a platform advocate

最好为每一种适配平台指定一位负责人。理想情况下，负责人以他们熟悉的平台为主，提供他们对平台特有的看法和意见。若想减少人员，兼顾角色，可以安排一位支持 Windows 和 Android，一位支持 Linux 和 Web，一位支持 Mac 和 iOS。

If possible, assign someone as an advocate for each platform. Ideally, your advocate uses the platform as their primary device, and can offer the perspective of a highly opinionated user. To reduce the number of people, combine roles. Have one advocate for Windows and Android, one for Linux and the web, and one for Mac and iOS.

这样做的目的是为了得到持续且有效的反馈，让应用在每个平台上都能表现良好。负责人应该以挑剔的角度对平台实现进行把关。一个非常简单的例子是在对话框里，对话框本身按钮的默认位置在 Mac 和 Linux 上通常位于左侧，而在 Windows 上位于右侧。如果你不是平台的常用用户，通常会错过这样的细节。

The goal is to have constant, informed feedback so the app feels great on each platform. Advocates should be encouraged to be quite picky, calling out anything they feel differs from typical applications on their device. A simple example is how the default button in a dialog is typically on the left on Mac and Linux, but is on the right on Windows. Details like that are easy to miss if you aren’t using a platform on a regular basis.

保持应用的独特

Stay unique

应用并不一定需要默认的组件或样式来保证其符合期望的行为。许多非常流行的多平台应用都有自成一派的 UI，包括自定义按钮、选项菜单和标题栏等。

Conforming to expected behaviors doesn’t mean that your app needs to use default components or styling. Many of the most popular multiplatform apps have very distinct and opinionated UIs including custom buttons, context menus, and title bars.

跨平台样式内容越多，开发和测试就越轻松。在构建你的用户体验时，要注意平衡对它们的选择，同时还要尊重各个平台的规范。

The more you can consolidate styling and behavior across platforms, the easier development and testing will be. The trick is to balance creating a unique experience with a strong identity, while respecting the norms of each platform.

需要考虑的常见平台行为习惯与规范

Common idioms and norms to consider

让我们来快速浏览一下你可能需要考虑的规范和习惯，了解一下在 Flutter 中如何实现它们。

Take a quick look at a few specific norms and idioms you might want to consider, and how you could approach them in Flutter.

滚动条的外观和行为

Scrollbar appearance and behavior

无论是桌面端还是移动端的用户，都需要滚动条，但他们对不同平台所期待的行为是不一样的。移动端的用户希望滚动条小一些，只在滚动时出现，而桌面端的用户一般想要更大且一直显示的滚动条，同时可以点击和拖动。

Desktop and mobile users expect scrollbars, but they expect them to behave differently on different platforms. Mobile users expect smaller scrollbars that only appear while scrolling, whereas desktop users generally expect omnipresent, larger scrollbars that they can click or drag.

Flutter 内置了 Scrollbar widget，会根据当前所在的平台自适应颜色和大小。你可能会需要调整 alwaysShown 以在桌面平台上一直显示滚动条：

Flutter comes with a built-in Scrollbar widget that already has support for adaptive colors and sizes according to the current platform. The one tweak you might want to make is to toggle alwaysShown when on a desktop platform:

return Scrollbar(
  isAlwaysShown: DeviceType.isDesktop,
  controller: _scrollController,
  child: GridView.count(
      controller: _scrollController,
      padding: EdgeInsets.all(Insets.extraLarge),
      childAspectRatio: 1,
      crossAxisCount: colCount,
      children: listChildren),
);

对这些细节的把握，可以让你的应用在对应平台上体验更为良好。

This subtle attention to detail can make your app feel more comfortable on a given platform.

多选

Multi-select

跨平台的另一个存在差异的地方，是如何处理列表中的多选：

Dealing with multi-select within a list is another area with subtle differences across platforms:

static bool get isSpanSelectModifierDown =>
    isKeyDown({LogicalKeyboardKey.shiftLeft, LogicalKeyboardKey.shiftRight});

要想监测不同平台的 Control 或 Command 键，你可以编写以下的代码：

To perform a platform-aware check for control or command, you can write something like this:

static bool get isMultiSelectModifierDown {
  bool isDown = false;
  if (Platform.isMacOS) {
    isDown = isKeyDown(
        {LogicalKeyboardKey.metaLeft, LogicalKeyboardKey.metaRight});
  } else {
    isDown = isKeyDown(
        {LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.controlRight});
  }
  return isDown;
}

最后一项针对键盘用户需要考虑的是全选操作。如果你的列表里有很多的可选择内容，可能你的许多用户也会希望能使用 Control+A 选中所有内容。

A final consideration for keyboard users is the Select All action. If you have a large list of items of selectable items, many of your keyboard users will expect that they can use Control+A to select all the items.

触屏设备

Touch devices

在触屏设备上，多选操作通常会被简化，与在桌面上按下了 isMultiSelectModifier（多选按钮）的行为类似。

On touch devices, multi-selection is typically simplified, with the expected behavior being similar to having the isMultiSelectModifier down on the desktop. You can select or deselect items using a single tap, and will usually have a button to Select All or Clear the current selection.

在不同设备上处理多选操作，取决于你的用例是否有区分，但更重要的是为各个平台提供最好的交互模式。

How you handle multi-selection on different devices depends on your specific use cases, but the important thing is to make sure that you’re offering each platform the best interaction model possible.

可选中的文字

Selectable text

对于 Web 平台（以及小部分的桌面平台）而言，大部分能看到的文字都是可以使用鼠标选择的。如果不能选择，用户可能会感到不正常。

A common expectation on the web (and to a lesser extent desktop) is that most visible text can be selected with the mouse cursor. When text is not selectable, users on the web tend to have an adverse reaction.

幸运的是，使用 SelectableText 就可以很简单地支持选择：

Luckily, this is easy to support with the SelectableText widget:

return SelectableText('Select me!');

可以用 TextSpan 支持富文本：

To support rich text, then use TextSpan:

return SelectableText.rich(
  TextSpan(
    children: [
      TextSpan(text: 'Hello'),
      TextSpan(text: 'Bold', style: TextStyle(fontWeight: FontWeight.bold)),
    ],
  ),
);

标题栏

Title bars

在现代的桌面应用程序中，经常会有定制应用窗口的标题栏、添加 Logo 或者其他控制的需求，能节省界面对于垂直空间的占用。

On modern desktop applications, it’s common to customize the title bar of your app window, adding a logo for stronger branding or contextual controls to help save vertical space in your main UI.

Samples of title bars

Flutter 并没有内置这样的支持，但是你可以使用 bits_dojo package 禁用标题栏，并且替换成自己的。

This isn’t supported directly in Flutter, but you can use the bits_dojo package to disable the native title bars, and replace them with your own.

你可以利用这个 package 将任意 widget 应用在标题栏上，因为它是基于 Flutter 的 widget 进行设置的。如此一来，当你在应用内各个地方浏览时，标题栏都能以非常便捷的方式进行适配。

This package lets you add whatever widgets you want to the TitleBar because it uses pure Flutter widgets under the hood. This makes it easy to adapt the title bar as you navigate to different sections of the app.

上下文菜单和提示

Context menus and tooltips

在桌面平台上，通常有几种在叠加层中显示的交互组件，它们各自有不同的触发、关闭和定位方式：

On desktop, there are several interactions that manifest as a widget shown in an overlay, but with differences in how they’re triggered, dismissed, and positioned:

上下文菜单——通常在右键单击时显示，上下文菜单会显示在鼠标点击位置的附近，可以点击任意位置关闭、点击选项关闭或点击外部区域关闭。
Context menu—Typically triggered by a right-click, a context menu is positioned close to the mouse, and is dismissed by clicking anywhere, selecting an option from the menu, or clicking outside it.
提示——提示通常会在交互元素上悬停 200-400 毫秒后出现，一般会锚定在 widget 上（与鼠标位置相反），并在鼠标移出元素后消失。
Tooltip—Typically triggered by hovering for 200-400ms over an interactive element, a tooltip is usually anchored to a widget (as opposed to the mouse position) and is dismissed when the mouse cursor leaves that widget.
悬浮面板（浮出控件）——悬浮面板与提示类似，通常会锚定在 widget 上。它与提示的区别是一般会在点击事件触发时显示，并且在鼠标移出时不会自动消失。通常来说，点击外部区域或者关闭或提交按钮时会关闭悬浮面板。
Popup panel (also known as flyout)—Similar to a tooltip, a popup panel is usually anchored to a widget. The main difference is that panels are most often shown on a tap event, and they usually don’t hide themselves when the cursor leaves. Instead, panels are typically dismissed by clicking outside the panel or by pressing a Close or Submit button.

若你想在 Flutter 中显示一个简单的提示，你可以使用 Tooltip widget：

To show basic tooltips in Flutter, use the built-in Tooltip widget:

return const Tooltip(
  message: 'I am a Tooltip',
  child: Text('Hover over the text to show a tooltip.'),
);

Flutter 同时也为编辑和选择文字提供了内置的上下文菜单。

Flutter also provides built-in context menus when editing or selecting text.

若你想显示更高级的提示、悬浮面板或自定义的上下文菜单，你可以使用已有的 package，或利用 Stack 和 Overlay 进行构建。

To show more advanced tooltips, popup panels, or create custom context menus, you either use one of the available packages, or build it yourself using a Stack or Overlay.

可以使用的 package 包括：

Some available packages include:

尽管这些控制对于触控用户来说只是一种增强，但对于桌面用户而言，它们是必不可少的。桌面用户会期望能够右键点击其中一些内容，当场进行编辑，悬浮时查看更多信息。若你的应用并不包含这类交互，相关的用户群体可能会感到有些失望，或是认为某些地方不合理。

While these controls can be valuable for touch users as accelerators, they are essential for mouse users. These users expect to right-click things, edit content in place, and hover for more information. Failing to meet those expectations can lead to disappointed users, or at least, a feeling that something isn’t quite right.

按钮的水平排列

Horizontal button order

在 Windows 上展示一行按钮时，确认按钮会在一行的起始位置（左侧）。而在其他平台上，则是完全相反的，确认按钮显示在末尾位置（右侧）。

On Windows, when presenting a row of buttons, the confirmation button is placed at the start of the row (left side). On all other platforms, it’s the opposite. The confirmation button is placed at the end of the row (right side).

在 Flutter 里你可以很轻松地修改 Row 的 TextDirection 来达到这个效果：

This can be easily handled in Flutter using the TextDirection property on Row:

TextDirection btnDirection =
    DeviceType.isWindows ? TextDirection.rtl : TextDirection.ltr;
return Row(
  children: [
    Spacer(),
    Row(
      textDirection: btnDirection,
      children: [
        DialogButton(
            label: "Cancel",
            onPressed: () => Navigator.pop(context, false)),
        DialogButton(
            label: "Ok", onPressed: () => Navigator.pop(context, true)),
      ],
    ),
  ],
);

Sample of embedded image

Menu bar

桌面平台有另一种常见的内容：菜单栏。在 Windows 和 Linux 上，Chrome 的菜单栏整合在标题栏内，而在 macOS 上，菜单栏在主屏幕的顶部。

Another common pattern on desktop apps is the menu bar. On Windows and Linux, this menu lives as part of the Chrome title bar, whereas on macOS, it’s located along the top of the primary screen.

目前你可以使用一个原型插件来指定菜单栏的入口，我们希望这个功能最终能合并到 SDK 中。

Currently, you can specify custom menu bar entries using a prototype plugin, but it’s expected that this functionality will eventually be integrated into the main SDK.

值得一提的是，在 Windows 和 Linux 上，你无法将自定义的标题栏与菜单栏整合在一起。在构建自定义的标题栏时，实际上是替换了整个原生的标题栏，意味着你也同时失去了原生的菜单栏。

It’s worth mentioning that on Windows and Linux, you can’t combine a custom title bar with a menu bar. When you create a custom title bar, you’re replacing the native one completely, which means you also lose the integrated native menu bar.

如果你同时需要自定义的标题栏和菜单栏，你可以使用 Flutter 进行实现，类似于自定义的上下文菜单。

If you need both a custom title bar and a menu bar, you can achieve that by implementing it in Flutter, similar to a custom context menu.

拖放（拖动和放置）

Drag and drop

拖放是基于触摸和指针的交互的一项核心。虽然这两种交互类型都需要拖放，但是在滑动整个包含可拖拽元素的列表时，仍然需要考虑其中的差异。

One of the core interactions for both touch-based and pointer-based inputs is drag and drop. Although this interaction is expected for both types of input, there are important differences to think about when it comes to scrolling lists of draggable items.

一般来说，触屏用户希望看到可拖动的手柄，以区分拖动和滚动的范围，或者通过长按操作来进行拖动。这是由于滑动和拖动操作都是由一个触摸点完成的。

Generally speaking, touch users expect to see drag handles to differentiate draggable areas from scrollable ones, or alternatively, to initiate a drag by using a long press gesture. This is because scrolling and dragging are both sharing a single finger for input.

鼠标用户有着不止一种输入方式。他们可以使用滚轮和滑动条进行滑动，这样便不再专门需要操作手柄进行指示操作。如果你使用过 macOS 的访达和 Windows 的资源管理器，你会看到它们在选中一个元素后，就可以开始拖动。

Mouse users have more input options. They can use a wheel or scrollbar to scroll, which generally eliminates the need for dedicated drag handles. If you look at the macOS Finder or Windows Explorer, you’ll see that they work this way: you just select an item and start dragging.

在 Flutter 中，你可以用多种方式实现拖放。但是我们不在本篇文章中讨论这个话题，以下是一些更高级的选项：

In Flutter, you can implement drag and drop in many ways. Discussing specific implementations is outside the scope of this article, but some high level options are:

使用 Draggable 和 DragTarget API 定制界面和交互。
Use the Draggable and DragTarget APIs directly for a custom look and feel.
监听 onPan 手势事件，利用 Stack 移动对象。
Hook into onPan gesture events, and move an object yourself within a parent Stack.
使用 pub.dev 上一些预先实现的 package。
Use one of the pre-made list packages on pub.dev.

自身做到熟悉基本的可用性原则

Educate yourself on basic usability principles

当然，这篇文章并不代表你仅需要考虑这些内容。针对平台设计的规范，会随着你适配的平台、设备外形和输入设备数量的增加而变得更为复杂。

Of course, this page doesn’t constitute an exhaustive list of the things you might consider. The more operating systems, form factors, and input devices you support, the more difficult it becomes to spec out every permutation in design.

作为开发人员，你应当花一些时间学习基本的可用性原则，帮助你做出更好的决策，减少由设计细节带来的返工时间消耗，从而提升自己的生产力，产出更好的结果。

Taking time to learn basic usability principles as a developer empowers you to make better decisions, reduces back-and-forth iterations with design during production, and results in improved productivity with better outcomes.

你可以从下列的资源开始学习：

Here are some resources to get you started:

深入理解 Flutter 布局约束

Hero image from the article

我们会经常听到一些开发者在学习 Flutter 时的疑惑：为什么我设置了 width:100，但是看上去却不是 100 像素宽呢。（注意，本文中的“像素”均指的是逻辑像素）通常你会回答，将这个 Widget 放进 Center 中，对吧？

When someone learning Flutter asks you why some widget with width:100 isn’t 100 pixels wide, the default answer is to tell them to put that widget inside of a Center, right?

别这么干。

Don’t do that.

如果你这样做了，他们会不断找你询问这样的问题：为什么 FittedBox 又不起作用了？为什么 Column 又溢出边界，亦或是 IntrinsicWidth 应该做什么。

If you do, they’ll come back again and again, asking why some FittedBox isn’t working, why that Column is overflowing, or what IntrinsicWidth is supposed to be doing.

其实我们首先应该做的，是告诉他们 Flutter 的布局方式与 HTML 的布局差异相当大（这些开发者很可能是 Web 开发），然后要让他们熟记这条规则：

Instead, first tell them that Flutter layout is very different from HTML layout (which is probably where they’re coming from), and then make them memorize the following rule:

首先，上层 widget 向下层 widget 传递约束条件；
然后，下层 widget 向上层 widget 传递大小信息。
最后，上层 widget 决定下层 widget 的位置。
Constraints go down. Sizes go up. Parent sets position.

如果我们在开发时无法熟练运用这条规则，在布局时就不能完全理解其原理，所以越早掌握这条规则越好！

Flutter layout can’t really be understood without knowing this rule, so Flutter developers should learn it early on.

更多细节：

In more detail:

Widget 会通过它的父级获得自身的约束。约束实际上就是 4 个浮点类型的集合：最大/最小宽度，以及最大/最小高度。
A widget gets its own constraints from its parent. A constraint is just a set of 4 doubles: a minimum and maximum width, and a minimum and maximum height.
然后，这个 widget 将会逐个遍历它的 children 列表。向子级传递约束（子级之间的约束可能会有所不同），然后询问它的每一个子级需要用于布局的大小。
Then the widget goes through its own list of children. One by one, the widget tells its children what their constraints are (which can be different for each child), and then asks each child what size it wants to be.
然后，这个 widget 就会对它子级的 children 逐个进行布局。（水平方向是 x 轴，竖直是 y 轴）
Then, the widget positions its children (horizontally in the x axis, and vertically in the y axis), one by one.
最后，widget 将会把它的大小信息向上传递至父 widget（包括其原始约束条件）。
And, finally, the widget tells its parent about its own size (within the original constraints, of course).

例如，如果一个 widget 中包含了一个具有 padding 的 Column，并且要对 Column 的子 widget 进行如下的布局：

For example, if a composed widget contains a column with some padding, and wants to lay out its two children as follows:

Visual layout

那么谈判将会像这样：

The negotiation goes something like this:

Widget: “嘿！我的父级。我的约束是多少？”

Widget: “Hey parent, what are my constraints?”

Parent: “你的宽度必须在 80 到 300 像素之间，高度必须在 30 到 85 之间。”

Parent: “You must be from 80 to 300 pixels wide, and 30 to 85 tall.”

Widget: “嗯…我想要 5 个像素的内边距，这样我的子级能最多拥有 290 个像素宽度和 75 个像素高度。”

Widget: “Hmmm, since I want to have 5 pixels of padding, then my children can have at most 290 pixels of width and 75 pixels of height.”

Widget: “嘿，我的第一个子级，你的宽度必须要在 0 到 290，长度在 0 到 75 之间。”

Widget: “Hey first child, You must be from 0 to 290 pixels wide, and 0 to 75 tall.”

First child: “OK，那我想要 290 像素的宽度，20 个像素的长度。”

First child: “OK, then I wish to be 290 pixels wide, and 20 pixels tall.”

Widget: “嗯…由于我想要将我的第二个子级放在第一个子级下面，所以我们仅剩 55 个像素的高度给第二个子级了。”

Widget: “Hmmm, since I want to put my second child below the first one, this leaves only 55 pixels of height for my second child.”

Widget: “嘿，我的第二个子级，你的宽度必须要在 0 到 290，长度在 0 到 55 之间。”

Widget: “Hey second child, You must be from 0 to 290 wide, and 0 to 55 tall.”

Second child: “OK，那我想要 140 像素的宽度，30 个像素的长度。”

Second child: “OK, I wish to be 140 pixels wide, and 30 pixels tall.”

Widget: “很好。我的第一个子级将被放在 x: 5 & y: 5 的位置，而我的第二个子级将在 x: 80 & y: 25 的位置。”

Widget: “Very well. My first child has position x: 5 and y: 5, and my second child has x: 80 and y: 25.”

Widget: “嘿，我的父级，我决定我的大小为 300 像素宽度，60 像素高度。”

Widget: “Hey parent, I’ve decided that my size is going to be 300 pixels wide, and 60 pixels tall.”

限制

Limitations

正如上述所介绍的布局规则中所说的那样， Flutter 的布局引擎有一些重要限制：

As a result of the layout rule mentioned above, Flutter’s layout engine has a few important limitations:

一个 widget 仅在其父级给其约束的情况下才能决定自身的大小。这意味着 widget 通常情况下 不能任意获得其想要的大小。
A widget can decide its own size only within the constraints given to it by its parent. This means a widget usually can’t have any size it wants.
一个 widget 无法知道，也不需要决定其在屏幕中的位置。因为它的位置是由其父级决定的。
A widget can’t know and doesn’t decide its own position in the screen, since it’s the widget’s parent who decides the position of the widget.
当轮到父级决定其大小和位置的时候，同样的也取决于它自身的父级。所以，在不考虑整棵树的情况下，几乎不可能精确定义任何 widget 的大小和位置。
Since the parent’s size and position, in its turn, also depends on its own parent, it’s impossible to precisely define the size and position of any widget without taking into consideration the tree as a whole.
如果子级想要拥有和父级不同的大小，然而父级没有足够的空间对其进行布局的话，子级的设置的大小可能会不生效。 这时请明确指定它的对齐方式
If a child wants a different size from its parent and the parent doesn’t have enough information to align it, then the child’s size might be ignored. Be specific when defining alignment.

样例

Examples

下面的示例由 DartPad 提供，具有良好的交互体验。使用下面水平滚动条的编号切换 29 个不同的示例。

For an interactive experience, use the following DartPad. Use the numbered horizontal scrolling bar to switch between 29 different examples.

import 'package:flutter/material.dart';

void main() => runApp(const HomePage());

const red = Colors.red;
const green = Colors.green;
const blue = Colors.blue;
const big = TextStyle(fontSize: 30);

//////////////////////////////////////////////////

class HomePage extends StatelessWidget {
  const HomePage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return const FlutterLayoutArticle([
      Example1(),
      Example2(),
      Example3(),
      Example4(),
      Example5(),
      Example6(),
      Example7(),
      Example8(),
      Example9(),
      Example10(),
      Example11(),
      Example12(),
      Example13(),
      Example14(),
      Example15(),
      Example16(),
      Example17(),
      Example18(),
      Example19(),
      Example20(),
      Example21(),
      Example22(),
      Example23(),
      Example24(),
      Example25(),
      Example26(),
      Example27(),
      Example28(),
      Example29(),
    ]);
  }
}

//////////////////////////////////////////////////

abstract class Example extends StatelessWidget {
  const Example({Key? key}) : super(key: key);

  String get code;

  String get explanation;
}

//////////////////////////////////////////////////

class FlutterLayoutArticle extends StatefulWidget {
  const FlutterLayoutArticle(
    this.examples, {
    Key? key,
  }) : super(key: key);

  final List<Example> examples;

  @override
  _FlutterLayoutArticleState createState() => _FlutterLayoutArticleState();
}

//////////////////////////////////////////////////

class _FlutterLayoutArticleState extends State<FlutterLayoutArticle> {
  late int count;
  late Widget example;
  late String code;
  late String explanation;

  @override
  void initState() {
    count = 1;
    code = const Example1().code;
    explanation = const Example1().explanation;

    super.initState();
  }

  @override
  void didUpdateWidget(FlutterLayoutArticle oldWidget) {
    super.didUpdateWidget(oldWidget);
    var example = widget.examples[count - 1];
    code = example.code;
    explanation = example.explanation;
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Flutter Layout Article',
      home: SafeArea(
        child: Material(
          color: Colors.black,
          child: FittedBox(
            child: Container(
              width: 400,
              height: 670,
              color: const Color(0xFFCCCCCC),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.center,
                children: [
                  Expanded(
                      child: ConstrainedBox(
                          constraints: const BoxConstraints.tightFor(
                              width: double.infinity, height: double.infinity),
                          child: widget.examples[count - 1])),
                  Container(
                    height: 50,
                    width: double.infinity,
                    color: Colors.black,
                    child: SingleChildScrollView(
                      scrollDirection: Axis.horizontal,
                      child: Row(
                        mainAxisSize: MainAxisSize.min,
                        children: [
                          for (int i = 0; i < widget.examples.length; i++)
                            Container(
                              width: 58,
                              padding:
                                  const EdgeInsets.only(left: 4.0, right: 4.0),
                              child: button(i + 1),
                            ),
                        ],
                      ),
                    ),
                  ),
                  Container(
                    child: Scrollbar(
                      child: SingleChildScrollView(
                        key: ValueKey(count),
                        child: Padding(
                          padding: const EdgeInsets.all(10.0),
                          child: Column(
                            children: [
                              Center(child: Text(code)),
                              const SizedBox(height: 15),
                              Text(
                                explanation,
                                style: TextStyle(
                                    color: Colors.blue[900],
                                    fontStyle: FontStyle.italic),
                              ),
                            ],
                          ),
                        ),
                      ),
                    ),
                    height: 273,
                    color: Colors.grey[50],
                  ),
                ],
              ),
            ),
          ),
        ),
      ),
    );
  }

  Widget button(int exampleNumber) {
    return Button(
      key: ValueKey('button$exampleNumber'),
      isSelected: count == exampleNumber,
      exampleNumber: exampleNumber,
      onPressed: () {
        showExample(
          exampleNumber,
          widget.examples[exampleNumber - 1].code,
          widget.examples[exampleNumber - 1].explanation,
        );
      },
    );
  }

  void showExample(int exampleNumber, String code, String explanation) {
    setState(() {
      count = exampleNumber;
      this.code = code;
      this.explanation = explanation;
    });
  }
}

//////////////////////////////////////////////////

class Button extends StatelessWidget {
  final bool isSelected;
  final int exampleNumber;
  final VoidCallback onPressed;

  const Button({
    required Key key,
    required this.isSelected,
    required this.exampleNumber,
    required this.onPressed,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return TextButton(
      style: TextButton.styleFrom(
        primary: Colors.white,
        backgroundColor: isSelected ? Colors.grey : Colors.grey[800],
      ),
      child: Text(exampleNumber.toString()),
      onPressed: () {
        Scrollable.ensureVisible(
          context,
          duration: const Duration(milliseconds: 350),
          curve: Curves.easeOut,
          alignment: 0.5,
        );
        onPressed();
      },
    );
  }
}
//////////////////////////////////////////////////

class Example1 extends Example {
  const Example1({Key? key}) : super(key: key);

  @override
  final code = 'Container(color: red)';

  @override
  final explanation = 'The screen is the parent of the Container, '
      'and it forces the Container to be exactly the same size as the screen.'
      '\n\n'
      'So the Container fills the screen and paints it red.';

  @override
  Widget build(BuildContext context) {
    return Container(color: red);
  }
}

//////////////////////////////////////////////////

class Example2 extends Example {
  const Example2({Key? key}) : super(key: key);

  @override
  final code = 'Container(width: 100, height: 100, color: red)';
  @override
  final String explanation =
      'The red Container wants to be 100x100, but it can\'t, '
      'because the screen forces it to be exactly the same size as the screen.'
      '\n\n'
      'So the Container fills the screen.';

  @override
  Widget build(BuildContext context) {
    return Container(width: 100, height: 100, color: red);
  }
}

//////////////////////////////////////////////////

class Example3 extends Example {
  const Example3({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: Container(width: 100, height: 100, color: red))';
  @override
  final String explanation =
      'The screen forces the Center to be exactly the same size as the screen,'
      'so the Center fills the screen.'
      '\n\n'
      'The Center tells the Container that it can be any size it wants, but not bigger than the screen.'
      'Now the Container can indeed be 100x100.';

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Container(width: 100, height: 100, color: red),
    );
  }
}

//////////////////////////////////////////////////

class Example4 extends Example {
  const Example4({Key? key}) : super(key: key);

  @override
  final code = 'Align(\n'
      '   alignment: Alignment.bottomRight,\n'
      '   child: Container(width: 100, height: 100, color: red))';
  @override
  final String explanation =
      'This is different from the previous example in that it uses Align instead of Center.'
      '\n\n'
      'Align also tells the Container that it can be any size it wants, but if there is empty space it won\'t center the Container. '
      'Instead, it aligns the Container to the bottom-right of the available space.';

  @override
  Widget build(BuildContext context) {
    return Align(
      alignment: Alignment.bottomRight,
      child: Container(width: 100, height: 100, color: red),
    );
  }
}

//////////////////////////////////////////////////

class Example5 extends Example {
  const Example5({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: Container(\n'
      '              color: red,\n'
      '              width: double.infinity,\n'
      '              height: double.infinity))';
  @override
  final String explanation =
      'The screen forces the Center to be exactly the same size as the screen,'
      'so the Center fills the screen.'
      '\n\n'
      'The Center tells the Container that it can be any size it wants, but not bigger than the screen.'
      'The Container wants to be of infinite size, but since it can\'t be bigger than the screen, it just fills the screen.';

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Container(
          width: double.infinity, height: double.infinity, color: red),
    );
  }
}

//////////////////////////////////////////////////

class Example6 extends Example {
  const Example6({Key? key}) : super(key: key);

  @override
  final code = 'Center(child: Container(color: red))';
  @override
  final String explanation =
      'The screen forces the Center to be exactly the same size as the screen,'
      'so the Center fills the screen.'
      '\n\n'
      'The Center tells the Container that it can be any size it wants, but not bigger than the screen.'
      '\n\n'
      'Since the Container has no child and no fixed size, it decides it wants to be as big as possible, so it fills the whole screen.'
      '\n\n'
      'But why does the Container decide that? '
      'Simply because that\'s a design decision by those who created the Container widget. '
      'It could have been created differently, and you have to read the Container documentation to understand how it behaves, depending on the circumstances. ';

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Container(color: red),
    );
  }
}

//////////////////////////////////////////////////

class Example7 extends Example {
  const Example7({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: Container(color: red\n'
      '      child: Container(color: green, width: 30, height: 30)))';
  @override
  final String explanation =
      'The screen forces the Center to be exactly the same size as the screen,'
      'so the Center fills the screen.'
      '\n\n'
      'The Center tells the red Container that it can be any size it wants, but not bigger than the screen.'
      'Since the red Container has no size but has a child, it decides it wants to be the same size as its child.'
      '\n\n'
      'The red Container tells its child that it can be any size it wants, but not bigger than the screen.'
      '\n\n'
      'The child is a green Container that wants to be 30x30.'
      '\n\n'
      'Since the red `Container` has no size but has a child, it decides it wants to be the same size as its child. '
      'The red color isn\'t visible, since the green Container entirely covers all of the red Container.';

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Container(
        color: red,
        child: Container(color: green, width: 30, height: 30),
      ),
    );
  }
}

//////////////////////////////////////////////////

class Example8 extends Example {
  const Example8({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: Container(color: red\n'
      '      padding: const EdgeInsets.all(20.0),\n'
      '      child: Container(color: green, width: 30, height: 30)))';
  @override
  final String explanation =
      'The red Container sizes itself to its children size, but it takes its own padding into consideration. '
      'So it is also 30x30 plus padding. '
      'The red color is visible because of the padding, and the green Container has the same size as in the previous example.';

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Container(
        padding: const EdgeInsets.all(20.0),
        color: red,
        child: Container(color: green, width: 30, height: 30),
      ),
    );
  }
}

//////////////////////////////////////////////////

class Example9 extends Example {
  const Example9({Key? key}) : super(key: key);

  @override
  final code = 'ConstrainedBox(\n'
      '   constraints: BoxConstraints(\n'
      '              minWidth: 70, minHeight: 70,\n'
      '              maxWidth: 150, maxHeight: 150),\n'
      '      child: Container(color: red, width: 10, height: 10)))';
  @override
  final String explanation =
      'You might guess that the Container has to be between 70 and 150 pixels, but you would be wrong. '
      'The ConstrainedBox only imposes ADDITIONAL constraints from those it receives from its parent.'
      '\n\n'
      'Here, the screen forces the ConstrainedBox to be exactly the same size as the screen, '
      'so it tells its child Container to also assume the size of the screen, '
      'thus ignoring its \'constraints\' parameter.';

  @override
  Widget build(BuildContext context) {
    return ConstrainedBox(
      constraints: const BoxConstraints(
        minWidth: 70,
        minHeight: 70,
        maxWidth: 150,
        maxHeight: 150,
      ),
      child: Container(color: red, width: 10, height: 10),
    );
  }
}

//////////////////////////////////////////////////

class Example10 extends Example {
  const Example10({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: ConstrainedBox(\n'
      '      constraints: BoxConstraints(\n'
      '                 minWidth: 70, minHeight: 70,\n'
      '                 maxWidth: 150, maxHeight: 150),\n'
      '        child: Container(color: red, width: 10, height: 10))))';
  @override
  final String explanation =
      'Now, Center allows ConstrainedBox to be any size up to the screen size.'
      '\n\n'
      'The ConstrainedBox imposes ADDITIONAL constraints from its \'constraints\' parameter onto its child.'
      '\n\n'
      'The Container must be between 70 and 150 pixels. It wants to have 10 pixels, so it will end up having 70 (the MINIMUM).';

  @override
  Widget build(BuildContext context) {
    return Center(
      child: ConstrainedBox(
        constraints: const BoxConstraints(
          minWidth: 70,
          minHeight: 70,
          maxWidth: 150,
          maxHeight: 150,
        ),
        child: Container(color: red, width: 10, height: 10),
      ),
    );
  }
}

//////////////////////////////////////////////////

class Example11 extends Example {
  const Example11({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: ConstrainedBox(\n'
      '      constraints: BoxConstraints(\n'
      '                 minWidth: 70, minHeight: 70,\n'
      '                 maxWidth: 150, maxHeight: 150),\n'
      '        child: Container(color: red, width: 1000, height: 1000))))';
  @override
  final String explanation =
      'Center allows ConstrainedBox to be any size up to the screen size.'
      'The ConstrainedBox imposes ADDITIONAL constraints from its \'constraints\' parameter onto its child'
      '\n\n'
      'The Container must be between 70 and 150 pixels. It wants to have 1000 pixels, so it ends up having 150 (the MAXIMUM).';

  @override
  Widget build(BuildContext context) {
    return Center(
      child: ConstrainedBox(
        constraints: const BoxConstraints(
          minWidth: 70,
          minHeight: 70,
          maxWidth: 150,
          maxHeight: 150,
        ),
        child: Container(color: red, width: 1000, height: 1000),
      ),
    );
  }
}

//////////////////////////////////////////////////

class Example12 extends Example {
  const Example12({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: ConstrainedBox(\n'
      '      constraints: BoxConstraints(\n'
      '                 minWidth: 70, minHeight: 70,\n'
      '                 maxWidth: 150, maxHeight: 150),\n'
      '        child: Container(color: red, width: 100, height: 100))))';
  @override
  final String explanation =
      'Center allows ConstrainedBox to be any size up to the screen size.'
      'ConstrainedBox imposes ADDITIONAL constraints from its \'constraints\' parameter onto its child.'
      '\n\n'
      'The Container must be between 70 and 150 pixels. It wants to have 100 pixels, and that\'s the size it has, since that\'s between 70 and 150.';

  @override
  Widget build(BuildContext context) {
    return Center(
      child: ConstrainedBox(
        constraints: const BoxConstraints(
          minWidth: 70,
          minHeight: 70,
          maxWidth: 150,
          maxHeight: 150,
        ),
        child: Container(color: red, width: 100, height: 100),
      ),
    );
  }
}

//////////////////////////////////////////////////

class Example13 extends Example {
  const Example13({Key? key}) : super(key: key);

  @override
  final code = 'UnconstrainedBox(\n'
      '   child: Container(color: red, width: 20, height: 50));';
  @override
  final String explanation =
      'The screen forces the UnconstrainedBox to be exactly the same size as the screen.'
      'However, the UnconstrainedBox lets its child Container be any size it wants.';

  @override
  Widget build(BuildContext context) {
    return UnconstrainedBox(
      child: Container(color: red, width: 20, height: 50),
    );
  }
}

//////////////////////////////////////////////////

class Example14 extends Example {
  const Example14({Key? key}) : super(key: key);

  @override
  final code = 'UnconstrainedBox(\n'
      '   child: Container(color: red, width: 4000, height: 50));';
  @override
  final String explanation =
      'The screen forces the UnconstrainedBox to be exactly the same size as the screen, '
      'and UnconstrainedBox lets its child Container be any size it wants.'
      '\n\n'
      'Unfortunately, in this case the Container has 4000 pixels of width and is too big to fit in the UnconstrainedBox, '
      'so the UnconstrainedBox displays the much dreaded "overflow warning".';

  @override
  Widget build(BuildContext context) {
    return UnconstrainedBox(
      child: Container(color: red, width: 4000, height: 50),
    );
  }
}

//////////////////////////////////////////////////

class Example15 extends Example {
  const Example15({Key? key}) : super(key: key);

  @override
  final code = 'OverflowBox(\n'
      '   minWidth: 0.0,'
      '   minHeight: 0.0,'
      '   maxWidth: double.infinity,'
      '   maxHeight: double.infinity,'
      '   child: Container(color: red, width: 4000, height: 50));';
  @override
  final String explanation =
      'The screen forces the OverflowBox to be exactly the same size as the screen, '
      'and OverflowBox lets its child Container be any size it wants.'
      '\n\n'
      'OverflowBox is similar to UnconstrainedBox, and the difference is that it won\'t display any warnings if the child doesn\'t fit the space.'
      '\n\n'
      'In this case the Container is 4000 pixels wide, and is too big to fit in the OverflowBox, '
      'but the OverflowBox simply shows as much as it can, with no warnings given.';

  @override
  Widget build(BuildContext context) {
    return OverflowBox(
      minWidth: 0.0,
      minHeight: 0.0,
      maxWidth: double.infinity,
      maxHeight: double.infinity,
      child: Container(color: red, width: 4000, height: 50),
    );
  }
}

//////////////////////////////////////////////////

class Example16 extends Example {
  const Example16({Key? key}) : super(key: key);

  @override
  final code = 'UnconstrainedBox(\n'
      '   child: Container(color: Colors.red, width: double.infinity, height: 100));';
  @override
  final String explanation =
      'This won\'t render anything, and you\'ll see an error in the console.'
      '\n\n'
      'The UnconstrainedBox lets its child be any size it wants, '
      'however its child is a Container with infinite size.'
      '\n\n'
      'Flutter can\'t render infinite sizes, so it throws an error with the following message: '
      '"BoxConstraints forces an infinite width."';

  @override
  Widget build(BuildContext context) {
    return UnconstrainedBox(
      child: Container(color: Colors.red, width: double.infinity, height: 100),
    );
  }
}

//////////////////////////////////////////////////

class Example17 extends Example {
  const Example17({Key? key}) : super(key: key);

  @override
  final code = 'UnconstrainedBox(\n'
      '   child: LimitedBox(maxWidth: 100,\n'
      '      child: Container(color: Colors.red,\n'
      '                       width: double.infinity, height: 100));';
  @override
  final String explanation = 'Here you won\'t get an error anymore, '
      'because when the LimitedBox is given an infinite size by the UnconstrainedBox, '
      'it passes a maximum width of 100 down to its child.'
      '\n\n'
      'If you swap the UnconstrainedBox for a Center widget, '
      'the LimitedBox won\'t apply its limit anymore (since its limit is only applied when it gets infinite constraints), '
      'and the width of the Container is allowed to grow past 100.'
      '\n\n'
      'This explains the difference between a LimitedBox and a ConstrainedBox.';

  @override
  Widget build(BuildContext context) {
    return UnconstrainedBox(
      child: LimitedBox(
        maxWidth: 100,
        child: Container(
          color: Colors.red,
          width: double.infinity,
          height: 100,
        ),
      ),
    );
  }
}

//////////////////////////////////////////////////

class Example18 extends Example {
  const Example18({Key? key}) : super(key: key);

  @override
  final code = 'FittedBox(\n'
      '   child: Text(\'Some Example Text.\'));';
  @override
  final String explanation =
      'The screen forces the FittedBox to be exactly the same size as the screen.'
      'The Text has some natural width (also called its intrinsic width) that depends on the amount of text, its font size, and so on.'
      '\n\n'
      'The FittedBox lets the Text be any size it wants, '
      'but after the Text tells its size to the FittedBox, '
      'the FittedBox scales the Text until it fills all of the available width.';

  @override
  Widget build(BuildContext context) {
    return const FittedBox(
      child: Text('Some Example Text.'),
    );
  }
}

//////////////////////////////////////////////////

class Example19 extends Example {
  const Example19({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: FittedBox(\n'
      '      child: Text(\'Some Example Text.\')));';
  @override
  final String explanation =
      'But what happens if you put the FittedBox inside of a Center widget? '
      'The Center lets the FittedBox be any size it wants, up to the screen size.'
      '\n\n'
      'The FittedBox then sizes itself to the Text, and lets the Text be any size it wants.'
      '\n\n'
      'Since both FittedBox and the Text have the same size, no scaling happens.';

  @override
  Widget build(BuildContext context) {
    return const Center(
      child: FittedBox(
        child: Text('Some Example Text.'),
      ),
    );
  }
}

////////////////////////////////////////////////////

class Example20 extends Example {
  const Example20({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: FittedBox(\n'
      '      child: Text(\'…\')));';
  @override
  final String explanation =
      'However, what happens if FittedBox is inside of a Center widget, but the Text is too large to fit the screen?'
      '\n\n'
      'FittedBox tries to size itself to the Text, but it can\'t be bigger than the screen. '
      'It then assumes the screen size, and resizes Text so that it fits the screen, too.';

  @override
  Widget build(BuildContext context) {
    return const Center(
      child: FittedBox(
        child: Text(
            'This is some very very very large text that is too big to fit a regular screen in a single line.'),
      ),
    );
  }
}

//////////////////////////////////////////////////

class Example21 extends Example {
  const Example21({Key? key}) : super(key: key);

  @override
  final code = 'Center(\n'
      '   child: Text(\'…\'));';
  @override
  final String explanation = 'If, however, you remove the FittedBox, '
      'the Text gets its maximum width from the screen, '
      'and breaks the line so that it fits the screen.';

  @override
  Widget build(BuildContext context) {
    return const Center(
      child: Text(
          'This is some very very very large text that is too big to fit a regular screen in a single line.'),
    );
  }
}

//////////////////////////////////////////////////

class Example22 extends Example {
  const Example22({Key? key}) : super(key: key);

  @override
  final code = 'FittedBox(\n'
      '   child: Container(\n'
      '      height: 20.0, width: double.infinity));';
  @override
  final String explanation =
      'FittedBox can only scale a widget that is BOUNDED (has non-infinite width and height).'
      'Otherwise, it won\'t render anything, and you\'ll see an error in the console.';

  @override
  Widget build(BuildContext context) {
    return FittedBox(
      child: Container(
        height: 20.0,
        width: double.infinity,
        color: Colors.red,
      ),
    );
  }
}

//////////////////////////////////////////////////

class Example23 extends Example {
  const Example23({Key? key}) : super(key: key);

  @override
  final code = 'Row(children:[\n'
      '   Container(color: red, child: Text(\'Hello!\'))\n'
      '   Container(color: green, child: Text(\'Goodbye!\'))]';
  @override
  final String explanation =
      'The screen forces the Row to be exactly the same size as the screen.'
      '\n\n'
      'Just like an UnconstrainedBox, the Row won\'t impose any constraints onto its children, '
      'and instead lets them be any size they want.'
      '\n\n'
      'The Row then puts them side-by-side, and any extra space remains empty.';

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Container(color: red, child: const Text('Hello!', style: big)),
        Container(color: green, child: const Text('Goodbye!', style: big)),
      ],
    );
  }
}

//////////////////////////////////////////////////

class Example24 extends Example {
  const Example24({Key? key}) : super(key: key);

  @override
  final code = 'Row(children:[\n'
      '   Container(color: red, child: Text(\'…\'))\n'
      '   Container(color: green, child: Text(\'Goodbye!\'))]';
  @override
  final String explanation =
      'Since the Row won\'t impose any constraints onto its children, '
      'it\'s quite possible that the children might be too big to fit the available width of the Row.'
      'In this case, just like an UnconstrainedBox, the Row displays the "overflow warning".';

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Container(
          color: red,
          child: const Text(
            'This is a very long text that '
            'won\'t fit the line.',
            style: big,
          ),
        ),
        Container(color: green, child: const Text('Goodbye!', style: big)),
      ],
    );
  }
}

//////////////////////////////////////////////////

class Example25 extends Example {
  const Example25({Key? key}) : super(key: key);

  @override
  final code = 'Row(children:[\n'
      '   Expanded(\n'
      '       child: Container(color: red, child: Text(\'…\')))\n'
      '   Container(color: green, child: Text(\'Goodbye!\'))]';
  @override
  final String explanation =
      'When a Row\'s child is wrapped in an Expanded widget, the Row won\'t let this child define its own width anymore.'
      '\n\n'
      'Instead, it defines the Expanded width according to the other children, and only then the Expanded widget forces the original child to have the Expanded\'s width.'
      '\n\n'
      'In other words, once you use Expanded, the original child\'s width becomes irrelevant, and is ignored.';

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Expanded(
          child: Center(
            child: Container(
              color: red,
              child: const Text(
                'This is a very long text that won\'t fit the line.',
                style: big,
              ),
            ),
          ),
        ),
        Container(color: green, child: const Text('Goodbye!', style: big)),
      ],
    );
  }
}

//////////////////////////////////////////////////

class Example26 extends Example {
  const Example26({Key? key}) : super(key: key);

  @override
  final code = 'Row(children:[\n'
      '   Expanded(\n'
      '       child: Container(color: red, child: Text(\'…\')))\n'
      '   Expanded(\n'
      '       child: Container(color: green, child: Text(\'Goodbye!\'))]';
  @override
  final String explanation =
      'If all of Row\'s children are wrapped in Expanded widgets, each Expanded has a size proportional to its flex parameter, '
      'and only then each Expanded widget forces its child to have the Expanded\'s width.'
      '\n\n'
      'In other words, Expanded ignores the preffered width of its children.';

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Expanded(
          child: Container(
            color: red,
            child: const Text(
              'This is a very long text that won\'t fit the line.',
              style: big,
            ),
          ),
        ),
        Expanded(
          child: Container(
            color: green,
            child: const Text(
              'Goodbye!',
              style: big,
            ),
          ),
        ),
      ],
    );
  }
}

//////////////////////////////////////////////////

class Example27 extends Example {
  const Example27({Key? key}) : super(key: key);

  @override
  final code = 'Row(children:[\n'
      '   Flexible(\n'
      '       child: Container(color: red, child: Text(\'…\')))\n'
      '   Flexible(\n'
      '       child: Container(color: green, child: Text(\'Goodbye!\'))]';
  @override
  final String explanation =
      'The only difference if you use Flexible instead of Expanded, '
      'is that Flexible lets its child be SMALLER than the Flexible width, '
      'while Expanded forces its child to have the same width of the Expanded.'
      '\n\n'
      'But both Expanded and Flexible ignore their children\'s width when sizing themselves.'
      '\n\n'
      'This means that it\'s IMPOSSIBLE to expand Row children proportionally to their sizes. '
      'The Row either uses the exact child\'s width, or ignores it completely when you use Expanded or Flexible.';

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Flexible(
          child: Container(
            color: red,
            child: const Text(
              'This is a very long text that won\'t fit the line.',
              style: big,
            ),
          ),
        ),
        Flexible(
          child: Container(
            color: green,
            child: const Text(
              'Goodbye!',
              style: big,
            ),
          ),
        ),
      ],
    );
  }
}

//////////////////////////////////////////////////

class Example28 extends Example {
  const Example28({Key? key}) : super(key: key);

  @override
  final code = 'Scaffold(\n'
      '   body: Container(color: blue,\n'
      '   child: Column(\n'
      '      children: [\n'
      '         Text(\'Hello!\'),\n'
      '         Text(\'Goodbye!\')])))';

  @override
  final String explanation =
      'The screen forces the Scaffold to be exactly the same size as the screen,'
      'so the Scaffold fills the screen.'
      '\n\n'
      'The Scaffold tells the Container that it can be any size it wants, but not bigger than the screen.'
      '\n\n'
      'When a widget tells its child that it can be smaller than a certain size, '
      'we say the widget supplies "loose" constraints to its child. More on that later.';

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Container(
        color: blue,
        child: Column(
          children: const [
            Text('Hello!'),
            Text('Goodbye!'),
          ],
        ),
      ),
    );
  }
}

//////////////////////////////////////////////////

class Example29 extends Example {
  const Example29({Key? key}) : super(key: key);

  @override
  final code = 'Scaffold(\n'
      '   body: Container(color: blue,\n'
      '   child: SizedBox.expand(\n'
      '      child: Column(\n'
      '         children: [\n'
      '            Text(\'Hello!\'),\n'
      '            Text(\'Goodbye!\')]))))';

  @override
  final String explanation =
      'If you want the Scaffold\'s child to be exactly the same size as the Scaffold itself, '
      'you can wrap its child with SizedBox.expand.'
      '\n\n'
      'When a widget tells its child that it must be of a certain size, '
      'we say the widget supplies "tight" constraints to its child. More on that later.';

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SizedBox.expand(
        child: Container(
          color: blue,
          child: Column(
            children: const [
              Text('Hello!'),
              Text('Goodbye!'),
            ],
          ),
        ),
      ),
    );
  }
}

//////////////////////////////////////////////////

如果你愿意的话，你还可以在这个 Github 仓库中获取其代码。

If you prefer, you can grab the code from this GitHub repo.

以下各节将介绍这些示例。

The examples are explained in the following sections.

样例 1

Example 1

Example 1 layout

Container(color: red)

整个屏幕作为 Container 的父级，并且强制 Container 变成和屏幕一样的大小。

The screen is the parent of the Container, and it forces the Container to be exactly the same size as the screen.

所以这个 Container 充满了整个屏幕，并绘制成红色。

So the Container fills the screen and paints it red.

样例 2

Example 2

Example 2 layout

Container(width: 100, height: 100, color: red)

红色的 Container 想要变成 100 x 100 的大小，但是它无法变成，因为屏幕强制它变成和屏幕一样的大小。

The red Container wants to be 100 × 100, but it can’t, because the screen forces it to be exactly the same size as the screen.

所以 Container 充满了整个屏幕。

So the Container fills the screen.

样例 3

Example 3

Example 3 layout

Center(
  child: Container(width: 100, height: 100, color: red),
)

屏幕强制 Center 变得和屏幕一样大，所以 Center 充满了屏幕。

The screen forces the Center to be exactly the same size as the screen, so the Center fills the screen.

然后 Center 告诉 Container 可以变成任意大小，但是不能超出屏幕。现在，Container 可以真正变成 100 × 100 大小了。

The Center tells the Container that it can be any size it wants, but not bigger than the screen. Now the Container can indeed be 100 × 100.

样例 4

Example 4

Example 4 layout

Align(
  alignment: Alignment.bottomRight,
  child: Container(width: 100, height: 100, color: red),
)

与上一个样例不同的是，我们使用了 Align 而不是 Center。

This is different from the previous example in that it uses Align instead of Center.

Align 同样也告诉 Container，你可以变成任意大小。但是，如果还留有空白空间的话，它不会居中 Container。相反，它将会在允许的空间内，把 Container 放在右下角（bottomRight）。

Align also tells the Container that it can be any size it wants, but if there is empty space it won’t center the Container. Instead, it aligns the container to the bottom-right of the available space.

样例 5

Example 5

Example 5 layout

Center(
  child: Container(
      width: double.infinity, height: double.infinity, color: red),
)

屏幕强制 Center 变得和屏幕一样大，所以 Center 充满屏幕。

The screen forces the Center to be exactly the same size as the screen, so the Center fills the screen.

然后 Center 告诉 Container 可以变成任意大小，但是不能超出屏幕。现在，Container 想要无限的大小，但是由于它不能比屏幕更大，所以就仅充满屏幕。

The Center tells the Container that it can be any size it wants, but not bigger than the screen. The Container wants to be of infinite size, but since it can’t be bigger than the screen, it just fills the screen.

样例 6

Example 6

Example 6 layout

Center(
  child: Container(color: red),
)

屏幕强制 Center 变得和屏幕一样大，所以 Center 充满屏幕。

The screen forces the Center to be exactly the same size as the screen, so the Center fills the screen.

然后 Center 告诉 Container 可以变成任意大小，但是不能超出屏幕。由于 Container 没有子级而且没有固定大小，所以它决定能有多大就有多大，所以它充满了整个屏幕。

The Center tells the Container that it can be any size it wants, but not bigger than the screen. Since the Container has no child and no fixed size, it decides it wants to be as big as possible, so it fills the whole screen.

但是，为什么 Container 做出了这个决定？非常简单，因为这个决定是由 Container widget 的创建者决定的。可能会因创造者而异，而且你还得阅读 Container 文档来理解不同场景下它的行为。

But why does the Container decide that? Simply because that’s a design decision by those who created the Container widget. It could have been created differently, and you have to read the Container documentation to understand how it behaves, depending on the circumstances.

样例 7

Example 7

Example 7 layout

Center(
  child: Container(
    color: red,
    child: Container(color: green, width: 30, height: 30),
  ),
)

屏幕强制 Center 变得和屏幕一样大，所以 Center 充满屏幕。

The screen forces the Center to be exactly the same size as the screen, so the Center fills the screen.

然后 Center 告诉红色的 Container 可以变成任意大小，但是不能超出屏幕。由于 Container 没有固定大小但是有子级，所以它决定变成它 child 的大小。

The Center tells the red Container that it can be any size it wants, but not bigger than the screen. Since the red Container has no size but has a child, it decides it wants to be the same size as its child.

然后红色的 Container 告诉它的 child 可以变成任意大小，但是不能超出屏幕。

The red Container tells its child that it can be any size it wants, but not bigger than the screen.

而它的 child 是一个想要 30 × 30 大小绿色的 Container。由于红色的 Container 和其子级一样大，所以也变为 30 × 30。由于绿色的 Container 完全覆盖了红色 Container，所以你看不见它了。

The child is a green Container that wants to be 30 × 30. Given that the red Container sizes itself to the size of its child, it is also 30 × 30. The red color isn’t visible because the green Container entirely covers the red Container.

样例 8

Example 8

Example 8 layout

Center(
  child: Container(
    padding: const EdgeInsets.all(20.0),
    color: red,
    child: Container(color: green, width: 30, height: 30),
  ),
)

红色 Container 变为其子级的大小，但是它将其 padding 带入了约束的计算中。所以它有一个 30 x 30 的外边距。由于这个外边距，所以现在你能看见红色了。而绿色的 Container 则还是和之前一样。

The red Container sizes itself to its children’s size, but it takes its own padding into consideration. So it is also 30 × 30 plus padding. The red color is visible because of the padding, and the green Container has the same size as in the previous example.

样例 9

Example 9

Example 9 layout

ConstrainedBox(
  constraints: const BoxConstraints(
    minWidth: 70,
    minHeight: 70,
    maxWidth: 150,
    maxHeight: 150,
  ),
  child: Container(color: red, width: 10, height: 10),
)

你可能会猜想 Container 的尺寸会在 70 到 150 像素之间，但并不是这样。 ConstrainedBox 仅对其从其父级接收到的约束下施加其他约束。

You might guess that the Container has to be between 70 and 150 pixels, but you would be wrong. The ConstrainedBox only imposes additional constraints from those it receives from its parent.

在这里，屏幕迫使 ConstrainedBox 与屏幕大小完全相同，因此它告诉其子 Widget 也以屏幕大小作为约束，从而忽略了其 constraints 参数带来的影响。

Here, the screen forces the ConstrainedBox to be exactly the same size as the screen, so it tells its child Container to also assume the size of the screen, thus ignoring its constraints parameter.

样例 10

Example 10

Example 10 layout

Center(
  child: ConstrainedBox(
    constraints: const BoxConstraints(
      minWidth: 70,
      minHeight: 70,
      maxWidth: 150,
      maxHeight: 150,
    ),
    child: Container(color: red, width: 10, height: 10),
  ),
)

现在，Center 允许 ConstrainedBox 达到屏幕可允许的任意大小。 ConstrainedBox 将 constraints 参数带来的约束附加到其子对象上。

Now, Center allows ConstrainedBox to be any size up to the screen size. The ConstrainedBox imposes additional constraints from its constraints parameter onto its child.

Container 必须介于 70 到 150 像素之间。虽然它希望自己有 10 个像素大小，但最终获得了 70 个像素（最小为 70）。

The Container must be between 70 and 150 pixels. It wants to have 10 pixels, so it ends up having 70 (the minimum).

样例 11

Example 11

Example 11 layout

Center(
  child: ConstrainedBox(
    constraints: const BoxConstraints(
      minWidth: 70,
      minHeight: 70,
      maxWidth: 150,
      maxHeight: 150,
    ),
    child: Container(color: red, width: 1000, height: 1000),
  ),
)

现在，Center 允许 ConstrainedBox 达到屏幕可允许的任意大小。 ConstrainedBox 将 constraints 参数带来的约束附加到其子对象上。

Center allows ConstrainedBox to be any size up to the screen size. The ConstrainedBox imposes additional constraints from its constraints parameter onto its child.

Container 必须介于 70 到 150 像素之间。虽然它希望自己有 1000 个像素大小，但最终获得了 150 个像素（最大为 150）。

The Container must be between 70 and 150 pixels. It wants to have 1000 pixels, so it ends up having 150 (the maximum).

样例 12

Example 12

Example 12 layout

Center(
  child: ConstrainedBox(
    constraints: const BoxConstraints(
      minWidth: 70,
      minHeight: 70,
      maxWidth: 150,
      maxHeight: 150,
    ),
    child: Container(color: red, width: 100, height: 100),
  ),
)

现在，Center 允许 ConstrainedBox 达到屏幕可允许的任意大小。 ConstrainedBox 将 constraints 参数带来的约束附加到其子对象上。

Center allows ConstrainedBox to be any size up to the screen size. The ConstrainedBox imposes additional constraints from its constraints parameter onto its child.

Container 必须介于 70 到 150 像素之间。虽然它希望自己有 100 个像素大小，因为 100 介于 70 至 150 的范围内，所以最终获得了 100 个像素。

The Container must be between 70 and 150 pixels. It wants to have 100 pixels, and that’s the size it has, since that’s between 70 and 150.

样例 13

Example 13

Example 13 layout

UnconstrainedBox(
  child: Container(color: red, width: 20, height: 50),
)

屏幕强制 UnconstrainedBox 变得和屏幕一样大，而 UnconstrainedBox 允许其子级的 Container 可以变为任意大小。

The screen forces the UnconstrainedBox to be exactly the same size as the screen. However, the UnconstrainedBox lets its child Container be any size it wants.

样例 14

Example 14

Example 14 layout

UnconstrainedBox(
  child: Container(color: red, width: 4000, height: 50),
)

屏幕强制 UnconstrainedBox 变得和屏幕一样大，而 UnconstrainedBox 允许其子级的 Container 可以变为任意大小。

The screen forces the UnconstrainedBox to be exactly the same size as the screen, and UnconstrainedBox lets its child Container be any size it wants.

不幸的是，在这种情况下，容器的宽度为 4000 像素，这实在是太大，以至于无法容纳在 UnconstrainedBox 中，因此 UnconstrainedBox 将显示溢出警告（overflow warning）。

Unfortunately, in this case the Container is 4000 pixels wide and is too big to fit in the UnconstrainedBox, so the UnconstrainedBox displays the much dreaded “overflow warning”.

样例 15

Example 15

Example 15 layout

OverflowBox(
  minWidth: 0.0,
  minHeight: 0.0,
  maxWidth: double.infinity,
  maxHeight: double.infinity,
  child: Container(color: red, width: 4000, height: 50),
)

屏幕强制 OverflowBox 变得和屏幕一样大，并且 OverflowBox 允许其子容器设置为任意大小。

The screen forces the OverflowBox to be exactly the same size as the screen, and OverflowBox lets its child Container be any size it wants.

OverflowBox 与 UnconstrainedBox 类似，但不同的是，如果其子级超出该空间，它将不会显示任何警告。

OverflowBox is similar to UnconstrainedBox; the difference is that it won’t display any warnings if the child doesn’t fit the space.

在这种情况下，容器的宽度为 4000 像素，并且太大而无法容纳在 OverflowBox 中，但是 OverflowBox 会全部显示，而不会发出警告。

In this case, the Container has 4000 pixels of width, and is too big to fit in the OverflowBox, but the OverflowBox simply shows as much as it can, with no warnings given.

样例 16

Example 16

Example 16 layout

UnconstrainedBox(
  child: Container(color: Colors.red, width: double.infinity, height: 100),
)

这将不会渲染任何东西，而且你能在控制台看到错误信息。

This won’t render anything, and you’ll see an error in the console.

UnconstrainedBox 让它的子级决定成为任何大小，但是其子级是一个具有无限大小的 Container。

The UnconstrainedBox lets its child be any size it wants, however its child is a Container with infinite size.

Flutter 无法渲染无限大的东西，所以它抛出以下错误： BoxConstraints forces an infinite width.（盒子约束强制使用了无限的宽度）

Flutter can’t render infinite sizes, so it throws an error with the following message: BoxConstraints forces an infinite width.

样例 17

Example 17

Example 17 layout

UnconstrainedBox(
  child: LimitedBox(
    maxWidth: 100,
    child: Container(
      color: Colors.red,
      width: double.infinity,
      height: 100,
    ),
  ),
)

这次你就不会遇到报错了。 UnconstrainedBox 给 LimitedBox 一个无限的大小；但它向其子级传递了最大为 100 的约束。

Here you won’t get an error anymore, because when the LimitedBox is given an infinite size by the UnconstrainedBox; it passes a maximum width of 100 down to its child.

如果你将 UnconstrainedBox 替换为 Center，则LimitedBox 将不再应用其限制（因为其限制仅在获得无限约束时才适用），并且容器的宽度允许超过 100。

If you swap the UnconstrainedBox for a Center widget, the LimitedBox won’t apply its limit anymore (since its limit is only applied when it gets infinite constraints), and the width of the Container is allowed to grow past 100.

上面的样例解释了 LimitedBox 和 ConstrainedBox 之间的区别。

This explains the difference between a LimitedBox and a ConstrainedBox.

样例 18

Example 18

Example 18 layout

const FittedBox(
  child: Text('Some Example Text.'),
)

屏幕强制 FittedBox 变得和屏幕一样大，而 Text 则是有一个自然宽度（也被称作 intrinsic 宽度），它取决于文本数量，字体大小等因素。

The screen forces the FittedBox to be exactly the same size as the screen. The Text has some natural width (also called its intrinsic width) that depends on the amount of text, its font size, and so on.

FittedBox 让 Text 可以变为任意大小。但是在 Text 告诉 FittedBox 其大小后， FittedBox 缩放文本直到填满所有可用宽度。

The FittedBox lets the Text be any size it wants, but after the Text tells its size to the FittedBox, the FittedBox scales the Text until it fills all of the available width.

样例 19

Example 19

Example 19 layout

const Center(
  child: FittedBox(
    child: Text('Some Example Text.'),
  ),
)

但如果你将 FittedBox 放进 Center widget 中会发生什么？ Center 将会让 FittedBox 能够变为任意大小，取决于屏幕大小。

But what happens if you put the FittedBox inside of a Center widget? The Center lets the FittedBox be any size it wants, up to the screen size.

FittedBox 然后会根据 Text 调整自己的大小，然后让 Text 可以变为所需的任意大小，由于二者具有同一大小，因此不会发生缩放。

The FittedBox then sizes itself to the Text, and lets the Text be any size it wants. Since both FittedBox and the Text have the same size, no scaling happens.

样例 20

Example 20

Example 20 layout

const Center(
  child: FittedBox(
    child: Text(
        'This is some very very very large text that is too big to fit a regular screen in a single line.'),
  ),
)

然而，如果 FittedBox 位于 Center 中，但 Text 太大而超出屏幕，会发生什么？

However, what happens if FittedBox is inside of a Center widget, but the Text is too large to fit the screen?

FittedBox 会尝试根据 Text 大小调整大小，但不能大于屏幕大小。然后假定屏幕大小，并调整 Text 的大小以使其也适合屏幕。

FittedBox tries to size itself to the Text, but it can’t be bigger than the screen. It then assumes the screen size, and resizes Text so that it fits the screen, too.

样例 21

Example 21

Example 21 layout

const Center(
  child: Text(
      'This is some very very very large text that is too big to fit a regular screen in a single line.'),
)

然而，如果你删除了 FittedBox， Text 则会从屏幕上获取其最大宽度，并在合适的地方换行。

If, however, you remove the FittedBox, the Text gets its maximum width from the screen, and breaks the line so that it fits the screen.

样例 22

Example 22

Example 22 layout

FittedBox(
  child: Container(
    height: 20.0,
    width: double.infinity,
    color: Colors.red,
  ),
)

FittedBox 只能在有限制的宽高中对子 widget 进行缩放（宽度和高度不会变得无限大）。否则，它将无法渲染任何内容，并且你会在控制台中看到错误。

FittedBox can only scale a widget that is bounded (has non-infinite width and height). Otherwise, it won’t render anything, and you’ll see an error in the console.

样例 23

Example 23

Example 23 layout

Row(
  children: [
    Container(color: red, child: const Text('Hello!', style: big)),
    Container(color: green, child: const Text('Goodbye!', style: big)),
  ],
)

屏幕强制 Row 变得和屏幕一样大，所以 Row 充满屏幕。

The screen forces the Row to be exactly the same size as the screen.

和 UnconstrainedBox 一样， Row 也不会对其子代施加任何约束，而是让它们成为所需的任意大小。 Row 然后将它们并排放置，任何多余的空间都将保持空白。

Just like an UnconstrainedBox, the Row won’t impose any constraints onto its children, and instead lets them be any size they want. The Row then puts them side-by-side, and any extra space remains empty.

样例 24

Example 24

Example 24 layout

Row(
  children: [
    Container(
      color: red,
      child: const Text(
        'This is a very long text that '
        'won\'t fit the line.',
        style: big,
      ),
    ),
    Container(color: green, child: const Text('Goodbye!', style: big)),
  ],
)

由于 Row 不会对其子级施加任何约束，因此它的 children 很有可能太大而超出 Row 的可用宽度。在这种情况下， Row 会和 UnconstrainedBox 一样显示溢出警告。

Since Row won’t impose any constraints onto its children, it’s quite possible that the children might be too big to fit the available width of the Row. In this case, just like an UnconstrainedBox, the Row displays the “overflow warning”.

样例 25

Example 25

Example 25 layout

Row(
  children: [
    Expanded(
      child: Center(
        child: Container(
          color: red,
          child: const Text(
            'This is a very long text that won\'t fit the line.',
            style: big,
          ),
        ),
      ),
    ),
    Container(color: green, child: const Text('Goodbye!', style: big)),
  ],
)

当 Row 的子级被包裹在了 Expanded widget 之后， Row 将不会再让其决定自身的宽度了。

When a Row’s child is wrapped in an Expanded widget, the Row won’t let this child define its own width anymore.

取而代之的是，Row 会根据所有 Expanded 的子级来计算其该有的宽度。

Instead, it defines the Expanded width according to the other children, and only then the Expanded widget forces the original child to have the Expanded’s width.

换句话说，一旦你使用 Expanded，子级自身的宽度就变得无关紧要，直接会被忽略掉。

In other words, once you use Expanded, the original child’s width becomes irrelevant, and is ignored.

样例 26

Example 26

Example 26 layout

Row(
  children: [
    Expanded(
      child: Container(
        color: red,
        child: const Text(
          'This is a very long text that won\'t fit the line.',
          style: big,
        ),
      ),
    ),
    Expanded(
      child: Container(
        color: green,
        child: const Text(
          'Goodbye!',
          style: big,
        ),
      ),
    ),
  ],
)

如果所有 Row 的子级都被包裹了 Expanded widget，每一个 Expanded 大小都会与其 flex 因子成比例，并且 Expanded widget 将会强制其子级具有与 Expanded 相同的宽度。

If all of Row’s children are wrapped in Expanded widgets, each Expanded has a size proportional to its flex parameter, and only then each Expanded widget forces its child to have the Expanded’s width.

换句话说，Expanded 忽略了其子 Widget 想要的宽度。

In other words, Expanded ignores the preferred width of its children.

样例 27

Example 27

Example 27 layout

Row(
  children: [
    Flexible(
      child: Container(
        color: red,
        child: const Text(
          'This is a very long text that won\'t fit the line.',
          style: big,
        ),
      ),
    ),
    Flexible(
      child: Container(
        color: green,
        child: const Text(
          'Goodbye!',
          style: big,
        ),
      ),
    ),
  ],
)

如果你使用 Flexible 而不是 Expanded 的话，唯一的区别是，Flexible 会让其子级具有与 Flexible 相同或者更小的宽度。而 Expanded 将会强制其子级具有和 Expanded 相同的宽度。但无论是 Expanded 还是 Flexible 在它们决定子级大小时都会忽略其宽度。

The only difference if you use Flexible instead of Expanded, is that Flexible lets its child have the same or smaller width than the Flexible itself, while Expanded forces its child to have the exact same width of the Expanded. But both Expanded and Flexible ignore their children’s width when sizing themselves.

样例 28

Example 28

Example 28 layout

Scaffold(
  body: Container(
    color: blue,
    child: Column(
      children: const [
        Text('Hello!'),
        Text('Goodbye!'),
      ],
    ),
  ),
)

屏幕强制 Scaffold 变得和屏幕一样大，所以 Scaffold 充满屏幕。然后 Scaffold 告诉 Container 可以变为任意大小，但不能超出屏幕。

The screen forces the Scaffold to be exactly the same size as the screen, so the Scaffold fills the screen. The Scaffold tells the Container that it can be any size it wants, but not bigger than the screen.

样例 29

Example 29

Example 29 layout

Scaffold(
  body: SizedBox.expand(
    child: Container(
      color: blue,
      child: Column(
        children: const [
          Text('Hello!'),
          Text('Goodbye!'),
        ],
      ),
    ),
  ),
)

如果你想要 Scaffold 的子级变得和 Scaffold 本身一样大的话，你可以将这个子级外包裹一个 SizedBox.expand。

If you want the Scaffold’s child to be exactly the same size as the Scaffold itself, you can wrap its child with SizedBox.expand.

严格约束（Tight） vs 宽松约束（loose）

Tight vs. loose constraints

以后你经常会听到一些约束为严格约束或宽松约束，你花点时间来弄明白它们是值得的。

It’s very common to hear that some constraint is “tight” or “loose”, so it’s worth knowing what that means.

严格约束给你了一种获得确切大小的选择。换句话来说就是，它的最大/最小宽度是一致的，高度也一样。

A tight constraint offers a single possibility, an exact size. In other words, a tight constraint has its maximum width equal to its minimum width; and has its maximum height equal to its minimum height.

如果你到 Flutter 的 box.dart 文件中搜索 BoxConstraints 构造器，你会发现以下内容：

If you go to Flutter’s box.dart file and search for the BoxConstraints constructors, you’ll find the following:

BoxConstraints.tight(Size size)
   : minWidth = size.width,
     maxWidth = size.width,
     minHeight = size.height,
     maxHeight = size.height;

如果你重新阅读样例 2，它告诉我们屏幕强制 Container 变得和屏幕一样大。为何屏幕能够做到这一点，原因就是给 Container 传递了严格约束。

If you revisit Example 2 above, it tells us that the screen forces the red Container to be exactly the same size as the screen. The screen does that, of course, by passing tight constraints to the Container.

一个宽松约束，换句话来说就是设置了最大宽度/高度，但是让允许其子 widget 获得比它更小的任意大小。换句话来说，宽松约束的最小宽度/高度为 0。

A loose constraint, on the other hand, sets the maximum width and height, but lets the widget be as small as it wants. In other words, a loose constraint has a minimum width and height both equal to zero:

BoxConstraints.loose(Size size)
   : minWidth = 0.0,
     maxWidth = size.width,
     minHeight = 0.0,
     maxHeight = size.height;

如果你访问样例 3，它将会告诉我们 Center 让红色的 Container 变得更小，但是不能超出屏幕。Center 能够做到这一点的原因就在于给 Container 的是一个宽松约束。总的来说，Center 起的作用就是从其父级（屏幕）那里获得的严格约束，为其子级（Container）转换为宽松约束。

If you revisit Example 3, it tells us that the Center lets the red Container be smaller, but not bigger than the screen. The Center does that, of course, by passing loose constraints to the Container. Ultimately, the Center’s very purpose is to transform the tight constraints it got from its parent (the screen) to loose constraints for its child (the Container).

了解如何为特定 widget 制定布局规则

Learning the layout rules for specific widgets

掌握通用布局是非常重要的，但这还不够。

Knowing the general layout rule is necessary, but it’s not enough.

应用一般规则时，每个 widget 都具有很大的自由度，所以没有办法只看 widget 的名称就知道可能它长什么样。

Each widget has a lot of freedom when applying the general rule, so there is no way of knowing what it will do by just reading the widget’s name.

如果你尝试推测，可能就会猜错。除非你已阅读 widget 的文档或研究了其源代码，否则你无法确切知道 widget 的行为。

If you try to guess, you’ll probably guess wrong. You can’t know exactly how a widget behaves unless you’ve read its documentation, or studied its source-code.

布局源代码通常很复杂，因此阅读文档是更好的选择。但是当你在研究布局源代码时，可以使用 IDE 的导航功能轻松找到它。

The layout source-code is usually complex, so it’s probably better to just read the documentation. However, if you decide to study the layout source-code, you can easily find it by using the navigating capabilities of your IDE.

下面是一个例子：

Here is an example:

在你的代码中找到一个 Column 并跟进到它的源代码。为此，请在 (Android Studio/IntelliJ) 中使用 command+B（macOS）或 control+B（Windows/Linux）。你将跳到 basic.dart 文件中。由于 Column 扩展了 Flex，请导航至 Flex 源代码（也位于 basic.dart 中）。
Find a Column in your code and navigate to its source code. To do this, use command+B (macOS) or control+B (Windows/Linux) in Android Studio or IntelliJ. You’ll be taken to the basic.dart file. Since Column extends Flex, navigate to the Flex source code (also in basic.dart).
向下滚动直到找到一个名为 createRenderObject() 的方法。如你所见，此方法返回一个 RenderFlex。它是 Column 的渲染对象，现在导航到 flex.dart 文件中的 RenderFlex 的源代码。
Scroll down until you find a method called createRenderObject(). As you can see, this method returns a RenderFlex. This is the render-object for the Column. Now navigate to the source-code of RenderFlex, which takes you to the flex.dart file.
向下滚动，直到找到 performLayout() 方法，由该方法执行列布局。
Scroll down until you find a method called performLayout(). This is the method that does the layout for the Column.

A goodbye layout

本文作者：Marcelo Glasberg

Article by Marcelo Glasberg

Marcelo Glasberg 最初在 Medium 发表 Flutter: The Advanced Layout Rule Even Beginners Must Know 本文。我们十分喜欢这篇文章，在征得他的允许后发布在 flutter.dev。再次感谢你，Marcelo! 你可以找到 GitHub 以及 pub.dev 找到 Marcelo。

Marcelo originally published this content as Flutter: The Advanced Layout Rule Even Beginners Must Know on Medium. We loved it and asked that he allow us to publish in on docs.flutter.dev, to which he graciously agreed. Thanks, Marcelo! You can find Marcelo on GitHub and pub.dev.

同时，还要感谢 Simon Lightfoot 创造了本文的标题图片。

Also, thanks to Simon Lightfoot for creating the header image at the top of the article.

处理边界约束 (Box constraints) 的问题

无边界约束
Unbounded constraints
Flex

Flutter 中的 widget 由在其底层的 RenderBox 对象渲染而成。渲染框由其父级 widget 给出约束，并根据这些约束调整自身尺寸大小。约束是由最小宽度、最大宽度、最小高度、最大高度四个方面构成；尺寸大小则由特定的宽度和高度两个方面构成。

In Flutter, widgets are rendered by their underlying RenderBox objects. Render boxes are given constraints by their parent, and size themselves within those constraints. Constraints consist of minimum and maximum widths and heights; sizes consist of a specific width and height.

一般来说，从如何处理约束的角度来看，有以下三种类型的渲染框：

Generally, there are three kinds of boxes, in terms of how they handle their constraints:

尽可能大。比如 Center 和 ListView 的渲染框。
Those that try to be as big as possible. For example, the boxes used by Center and ListView.
与子 widget 一样大，比如 Transform 和 Opacity 的渲染框。
Those that try to be the same size as their children. For example, the boxes used by Transform and Opacity.
特定大小，比如 Image 和 Text 的渲染框。
Those that try to be a particular size. For example, the boxes used by Image and Text.

对于一些诸如 Container 的 widget，其尺寸会因构造方法的参数而异，就 Container 来说，它默认是尽可能大的，而一旦给它一个特定的宽度，那么它就会遵照这个特定的宽度来调整自身尺寸。

Some widgets, for example Container, vary from type to type based on their constructor arguments. In the case of Container, it defaults to trying to be as big as possible, but if you give it a width, for instance, it tries to honor that and be that particular size.

其它一些像 Row and Column (flex boxes)这样的 widget ，其尺寸会因给定的约束而异，具体细节见后文 “Flex” 部分；

Others, for example Row and (flex boxes) vary based on the constraints they are given, as described below in the “Flex” section.

约束有时是”紧密的”，这意味着这些约束严格地限定了渲染框在定夺自身尺寸方面的空间（例如：当约束的最小宽度和最大宽度相同时，这种情况下，我们称这个约束有紧密宽度），这方面的主要例子是 App Widget，它是 RenderView 类里面的一个 widget: 由应用程序的 build 函数返回的子 widget 渲染框被指定了一个约束，该约束强制 App Widget 精确填充应用程序的内容区域(通常是整个屏幕)。 Flutter 中的许多渲染框，特别是那些只包含单个 widget 的渲染框，都会将自身的约束传递给他们的子级 widget。这意味着如果你在应用程序渲染树的根部嵌套了一些渲染框，这些框将会在受到约束的影响下相互适应彼此。

The constraints are sometimes “tight”, meaning that they leave no room for the render box to decide on a size (for example, if the minimum and maximum width are the same, it is said to have a tight width). An example of this is the App widget, which is contained by the RenderView class: the box used by the child returned by the application’s build function is given a constraint that forces it to exactly fill the application’s content area (typically, the entire screen). Many of the boxes in Flutter, especially those that just take a single child, pass their constraint on to their children. This means that if you nest a bunch of boxes inside each other at the root of your application’s render tree, they’ll all exactly fit in each other, forced by these tight constraints.

有些渲染框放松了约束，即：约束中只有最大宽度，最大高度，但没有最小宽度，最小高度，例如 Center。

Some boxes loosen the constraints, meaning the maximum is maintained but the minimum is removed. For example, Center.

无边界约束

Unbounded constraints

在某些情况下，传递给框的约束是 无边界 的或无限的。这意味着约束的最大宽度或最大高度为 double.infinity。

In certain situations, the constraint that is given to a box is unbounded, or infinite. This means that either the maximum width or the maximum height is set to double.infinity.

当传递无边界约束给类型为尽可能大的框时会失效，在 debug 模式下，则会抛出异常，该异常信息会把你引导到本页面。

A box that tries to be as big as possible won’t function usefully when given an unbounded constraint and, in debug mode, such a combination throws an exception that points to this file.

渲染框具有无边界约束的最常见情况是：当其被置于 flex boxes (Row 和 Column)内以及 可滚动区域(ListView 和其它 ScrollView 的子类)内时。

The most common cases where a render box finds itself with unbounded constraints are within flex boxes (Row and Column), and within scrollable regions (ListView and other ScrollView subclasses).

特别是 ListView 会试图扩展以适应其交叉方向可用空间 (比如说，如果它是一个垂直滚动块，它将试图扩充到与其父 widget 一样宽)。如果让垂直滚动的 ListView 嵌套在水平滚动的 ListView 内，那么被嵌套在里面的垂直滚动的 ListView 将会试图尽可能宽，直到无限宽，因为将其嵌套的是一个水平滚动的ListView，它可以在水平方向上一直滚动。

In particular, ListView tries to expand to fit the space available in its cross-direction (for example, if it’s a vertically-scrolling block, it tries to be as wide as its parent). If you nest a vertically scrolling ListView inside a horizontally scrolling ListView, the inner one tries to be as wide as possible, which is infinitely wide, since the outer one is scrollable in that direction.

Flex

Flex 框本身(Row 和 Column)的行为会有所不同，这取决于其在给定方向上是处于有边界约束还是无边界约束。

Flex boxes themselves (Row and Column) behave differently based on whether they are in bounded constraints or unbounded constraints in their given direction.

在有边界约束条件下，它们在给定方向上会尽可能大。

In bounded constraints, they try to be as big as possible in that direction.

在无边界约束条件下，它们试图让其子 widget 自适应这个给定的方向。在这种情况下，不能将子 widget 的flex属性设置为 0（默认值）以外的任何值。这意味着在 widget 库中，当一个 flex 框嵌套在另外一个 flex 框或者嵌套在可滚动区域内时，不能使用 Expanded。如果这样做了，就会收到异常，该异常信息会把你引导到本页面。

In unbounded constraints, they try to fit their children in that direction. In this case, you cannot set flex on the children to anything other than 0. In the widget library, this means that you cannot use Expanded when the flex box is inside another flex box or inside a scrollable. If you do, you’ll get an exception message pointing you at this document.

在交叉方向上，如 Column（垂直的 flex）的宽度和 Row（水平的 flex）的高度，它们必将不能是无界的，否则它们将无法合理地对齐它们的子 widget。

In the cross direction, for example, in the width for Column (vertical flex) or in the height for Row (horizontal flex), they must never be unbounded, otherwise they would not be able to reasonably align their children.

为你的 Flutter 应用加入交互体验

有状态和无状态的 widgets
Stateful and stateless widgets
创建一个有状态的 widget
Creating a stateful widget
状态管理
Managing state
其他交互式 widgets
Other interactive widgets
- 标准 widgets
  Standard widgets
- Material 组件
  Material Components
资源
Resources

如何修改您的应用程序以使其对用户输入做出反应？在本教程中，您将为仅包含非交互式 widget 的应用程序添加交互性。具体来说，您将通过创建一个管理两个无状态 widget 的自定义有状态 widget，修改一个图标实现使其可点击。

How do you modify your app to make it react to user input? In this tutorial, you’ll add interactivity to an app that contains only non-interactive widgets. Specifically, you’ll modify an icon to make it tappable by creating a custom stateful widget that manages two stateless widgets.

构建布局教程中展示了如何构建下面截图所示的布局。

The building layouts tutorial showed you how to create the layout for the following screenshot.

当应用第一次启动时，这个星形图标是实心红色，表明这个湖以前已经被收藏过了。星号旁边的数字表示 41 个人已经收藏了此湖。完成本教程后，点击星形图标将取消收藏状态，然后用轮廓线的星形图标代替实心的，并减少计数。再次点击会重新收藏，并增加计数。

When the app first launches, the star is solid red, indicating that this lake has previously been favorited. The number next to the star indicates that 41 people have favorited this lake. After completing this tutorial, tapping the star removes its favorited status, replacing the solid star with an outline and decreasing the count. Tapping again favorites the lake, drawing a solid star and increasing the count.

The custom widget you'll create

为了实现这个，您将创建一个包含星形图标和计数的自定义 widget，它们都是 widget。因为点击星形图标会更改这两个 widget 的状态，所以同一个 widget 应该同时管理这两个 widget。

To accomplish this, you’ll create a single custom widget that includes both the star and the count, which are themselves widgets. Tapping the star changes state for both widgets, so the same widget should manage both.

您可以直接查看第二步: 创建 StatefulWidget 的子类。如果您想尝试不同的管理状态方式，请跳至状态管理。

You can get right to touching the code in Step 2: Subclass StatefulWidget. If you want to try different ways of managing state, skip to Managing state.

有状态和无状态的 widgets

Stateful and stateless widgets

有些 widgets 是有状态的, 有些是无状态的。如果用户与 widget 交互，widget 会发生变化，那么它就是 有状态的。

A widget is either stateful or stateless. If a widget can change—when a user interacts with it, for example—it’s stateful.

无状态的 widget 自身无法改变。 Icon、IconButton 和 Text 都是无状态 widget，它们都是 StatelessWidget 的子类。

A stateless widget never changes. Icon, IconButton, and Text are examples of stateless widgets. Stateless widgets subclass StatelessWidget.

而 有状态的 widget 自身是可动态改变的（基于State）。例如，可以通过与用户的交互或是随着数据的改变而导致外观形态的变化。 Checkbox、Radio、Slider、 InkWell、Form 和 TextField 都是有状态 widget，它们都是 StatefulWidget 的子类。

A stateful widget is dynamic: for example, it can change its appearance in response to events triggered by user interactions or when it receives data. Checkbox, Radio, Slider, InkWell, Form, and TextField are examples of stateful widgets. Stateful widgets subclass StatefulWidget.

一个 widget 的状态保存在一个 State 对象中，它和 widget 的显示分离。 Widget 的状态是一些可以更改的值，如一个滑动条的当前值或一个复选框是否被选中。当 widget 状态改变时，State 对象调用 setState()，告诉框架去重绘 widget。

A widget’s state is stored in a State object, separating the widget’s state from its appearance. The state consists of values that can change, like a slider’s current value or whether a checkbox is checked. When the widget’s state changes, the state object calls setState(), telling the framework to redraw the widget.

Creating a stateful widget

在本节中，您将创建一个自定义有状态的 widget。您将使用一个自定义有状态 widget 来替换两个无状态 widget—— 红色实心星形图标和其旁边的数字计数—— 该 widget 用两个子 widget 管理一行 IconButton 和 Text。

In this section, you’ll create a custom stateful widget. You’ll replace two stateless widgets—the solid red star and the numeric count next to it—with a single custom stateful widget that manages a row with two children widgets: an IconButton and Text.

实现一个自定义的有状态 widget 需要创建两个类：

Implementing a custom stateful widget requires creating two classes:

一个 StatefulWidget 的子类，用来定义一个 widget 类。
A subclass of StatefulWidget that defines the widget.
一个 State 的子类，包含该widget状态并定义该 widget 的 build() 方法。
A subclass of State that contains the state for that widget and defines the widget’s build() method.

这一节展示如何为 Lakes 应用程序构建一个名为 FavoriteWidget 的 StatefulWidget。第一步是选择如何管理 FavoriteWidget 的状态。

This section shows you how to build a stateful widget, called FavoriteWidget, for the lakes app. After setting up, your first step is choosing how state is managed for FavoriteWidget.

步骤 0: 开始

Step 0: Get ready

如果你已经在构建布局教程（第 6 步）中成功创建了应用程序，你可以跳过下面的部分。

If you’ve already built the app in the building layouts tutorial (step 6), skip to the next section.

确保你已经设置好了你的环境。
Make sure you’ve set up your environment.
创建一个基础的「Hello world」Flutter 应用。
Create a basic “Hello World” Flutter app.
用 GitHub 上的 main.dart 替换 lib/main.dart 文件。
Replace the lib/main.dart file with main.dart.
用 GitHub 上的 pubspec.yaml 替换 pubspec.yaml 文件。
Replace the pubspec.yaml file with pubspec.yaml.
在你的工程中创建一个 images 文件夹，并添加 lake.jpg。
Create an images directory in your project, and add lake.jpg.

如果你有一个连接并可用的设备，或者你已经启动了 iOS 模拟器或者 Android 模拟器（Flutter 安装部分介绍过），你就可以开始了！

Once you have a connected and enabled device, or you’ve launched the iOS simulator (part of the Flutter install) or the Android emulator (part of the Android Studio install), you are good to go!

Step 1: 决定哪个对象管理 widget 的状态

Step 1: Decide which object manages the widget’s state

一个 widget 的状态可以通过多种方式进行管理，但在我们的示例中，widget 本身 ——FavoriteWidget—— 将管理自己的状态。在这个例子中，切换星形图标是一个独立的操作，不会影响父窗口 widget 或其他用户界面，因此该 widget 可以在内部处理它自己的状态。

A widget’s state can be managed in several ways, but in our example the widget itself, FavoriteWidget, will manage its own state. In this example, toggling the star is an isolated action that doesn’t affect the parent widget or the rest of the UI, so the widget can handle its state internally.

你可以在状态管理中了解更多关于 widget 和状态的分离以及如何管理状态的信息。

Learn more about the separation of widget and state, and how state might be managed, in Managing state.

Step 2: 创建 StatefulWidget 的子类

Step 2: Subclass StatefulWidget

FavoriteWidget 类管理自己的状态，因此它通过重写 createState() 来创建状态对象。框架会在构建 widget 时调用 createState()。在这个例子中，createState() 创建 _FavoriteWidgetState 的实例，您将在下一步中实现该实例。

The FavoriteWidget class manages its own state, so it overrides createState() to create a State object. The framework calls createState() when it wants to build the widget. In this example, createState() returns an instance of _FavoriteWidgetState, which you’ll implement in the next step.

class FavoriteWidget extends StatefulWidget {
  const FavoriteWidget({Key? key}) : super(key: key);

  @override
  _FavoriteWidgetState createState() => _FavoriteWidgetState();
}

Step 3: 创建 State 的子类

Step 3: Subclass State

_FavoriteWidgetState 类存储可变信息；可以在 widget 的生命周期内改变逻辑和内部状态。当应用第一次启动时，用户界面显示一个红色实心的星星形图标，表明该湖已经被收藏，并有 41 个「喜欢」。状态对象存储这些信息在 _isFavorited 和 _favoriteCount 变量中。

The _FavoriteWidgetState class stores the mutable data that can change over the lifetime of the widget. When the app first launches, the UI displays a solid red star, indicating that the lake has “favorite” status, along with 41 likes. These values are stored in the _isFavorited and _favoriteCount fields:

class _FavoriteWidgetState extends State<FavoriteWidget> {
  bool _isFavorited = true;
  int _favoriteCount = 41;

  // ···
}

状态对象也定义了 build() 方法。这个 build() 方法创建一个包含红色 IconButton 和 Text 的行。该 widget 使用 IconButton（而不是 Icon），因为它具有一个 onPressed 属性，该属性定义了处理点击的回调方法 (_toggleFavorite)。你将会在接下来的步骤中尝试定义它。

The class also defines a build() method, which creates a row containing a red IconButton, and Text. You use IconButton (instead of Icon) because it has an onPressed property that defines the callback function (_toggleFavorite) for handling a tap. You’ll define the callback function next.

class _FavoriteWidgetState extends State<FavoriteWidget> {
  // ···
  @override
  Widget build(BuildContext context) {
    return Row(
      mainAxisSize: MainAxisSize.min,
      children: [
        Container(
          padding: const EdgeInsets.all(0),
          child: IconButton(
            padding: const EdgeInsets.all(0),
            alignment: Alignment.centerRight,
            icon: (_isFavorited
                ? const Icon(Icons.star)
                : const Icon(Icons.star_border)),
            color: Colors.red[500],
            onPressed: _toggleFavorite,
          ),
        ),
        SizedBox(
          width: 18,
          child: SizedBox(
            child: Text('$_favoriteCount'),
          ),
        ),
      ],
    );
  }
}

按下 IconButton 时会调用 _toggleFavorite() 方法，然后它会调用 setState()。调用 setState() 是至关重要的，因为这告诉框架， widget 的状态已经改变，应该重绘。 setState() 在如下两种状态中切换 UI：

The _toggleFavorite() method, which is called when the IconButton is pressed, calls setState(). Calling setState() is critical, because this tells the framework that the widget’s state has changed and that the widget should be redrawn. The function argument to setState() toggles the UI between these two states:

实心的星形图标和数字 41
A star icon and the number 41
轮廓线的星形图标 star_border 和数字 40 之间切换 UI
A star_border icon and the number 40

void _toggleFavorite() {
  setState(() {
    if (_isFavorited) {
      _favoriteCount -= 1;
      _isFavorited = false;
    } else {
      _favoriteCount += 1;
      _isFavorited = true;
    }
  });
}

Step 4: Plug the stateful widget into the widget tree

将您自定义 stateful widget 在 build() 方法中添加到 widget 树中。首先，找到创建 Icon 和 Text 的代码，并删除它，在相同的位置创建有状态的 widget：

Add your custom stateful widget to the widget tree in the app’s build() method. First, locate the code that creates the Icon and Text, and delete it. In the same location, create the stateful widget:

layout/lakes/{step6 → interactive}/lib/main.dart Viewed

@@ -10,2 +5,2 @@
 class MyApp extends StatelessWidget {
   const MyApp({Key? key}) : super(key: key);
@@ -40,11 +35,7 @@
               ],
             ),
           ),
- Icon(
-            Icons.star,
-            color: Colors.red[500],
-          ),
-          const Text('41'),
+ const FavoriteWidget(),
         ],
       ),
     );

就是这样！当您热重载应用后，星形图标就会响应点击了。

That’s it! When you hot reload the app, the star icon should now respond to taps.

有问题?

Problems?

如果您的代码无法运行，请在 IDE 中查找可能的错误。调试 Flutter 应用程序可能会有所帮助。如果仍然无法找到问题，请根据 GitHub 上的示例检查代码。

If you can’t get your code to run, look in your IDE for possible errors. Debugging Flutter apps might help. If you still can’t find the problem, check your code against the interactive lakes example on GitHub.

如果您仍有问题，可以咨询社区中的任何一位开发者。

If you still have questions, refer to any one of the developer community channels.

本页面的其余部分介绍了可以管理 widget 状态的几种方式，并列出了其他可用的可交互的 widget。

The rest of this page covers several ways a widget’s state can be managed, and lists other available interactive widgets.

状态管理

Managing state

谁管理着 stateful widget 的状态？widget 本身？父 widget？双方？另一个对象？答案是…… 这取决于实际情况。有几种有效的方法可以给你的 widget 加入交互。作为 widget 设计师，你可以基于你所期待的表现 widget 的方式来做决定。以下是一些管理状态的最常见的方法：

Who manages the stateful widget’s state? The widget itself? The parent widget? Both? Another object? The answer is… it depends. There are several valid ways to make your widget interactive. You, as the widget designer, make the decision based on how you expect your widget to be used. Here are the most common ways to manage state:

widget 管理自己的状态
The widget manages its own state
父 widget 管理此 widget 的状态
The parent manages the widget’s state
混搭管理
A mix-and-match approach

如何决定使用哪种管理方法？以下原则可以帮助您决定：

How do you decide which approach to use? The following principles should help you decide:

如果状态是用户数据，如复选框的选中状态、滑块的位置，则该状态最好由父 widget 管理。
If the state in question is user data, for example the checked or unchecked mode of a checkbox, or the position of a slider, then the state is best managed by the parent widget.
如果所讨论的状态是有关界面外观效果的，例如动画，那么状态最好由 widget 本身来管理。
If the state in question is aesthetic, for example an animation, then the state is best managed by the widget itself.

如果有疑问，首选是在父 widget 中管理状态。

If in doubt, start by managing state in the parent widget.

我们将通过创建三个简单示例来举例说明管理状态的不同方式： TapboxA、TapboxB 和 TapboxC。这些例子功能是相似的—— 每创建一个容器，当点击时，在绿色或灰色框之间切换。 _active 确定颜色：绿色为 true，灰色为 false。

We’ll give examples of the different ways of managing state by creating three simple examples: TapboxA, TapboxB, and TapboxC. The examples all work similarly—each creates a container that, when tapped, toggles between a green or grey box. The _active boolean determines the color: green for active or grey for inactive.

这些示例使用 GestureDetector 捕获 Container 上的用户动作。

These examples use GestureDetector to capture activity on the Container.

The widget manages its own state

有时，widget 在内部管理其状态是最好的。例如，当 ListView 的内容超过渲染框时， ListView 自动滚动。大多数使用 ListView 的开发人员不想管理 ListView 的滚动行为，因此 ListView 本身管理其滚动偏移量。

Sometimes it makes the most sense for the widget to manage its state internally. For example, ListView automatically scrolls when its content exceeds the render box. Most developers using ListView don’t want to manage ListView’s scrolling behavior, so ListView itself manages its scroll offset.

_TapboxAState 类:

The _TapboxAState class:

管理 TapboxA 的状态。
Manages state for TapboxA.
定义布尔值 _active 确定盒子的当前颜色。
Defines the _active boolean which determines the box’s current color.
定义 _handleTap() 函数，该函数在点击该盒子时更新 _active，并调用 setState() 更新 UI。
Defines the _handleTap() function, which updates _active when the box is tapped and calls the setState() function to update the UI.
实现 widget 的所有交互式行为。
Implements all interactive behavior for the widget.

import 'package:flutter/material.dart';

// TapboxA manages its own state.

//------------------------- TapboxA ----------------------------------

class TapboxA extends StatefulWidget {
  const TapboxA({Key? key}) : super(key: key);

  @override
  _TapboxAState createState() => _TapboxAState();
}

class _TapboxAState extends State<TapboxA> {
  bool _active = false;

  void _handleTap() {
    setState(() {
      _active = !_active;
    });
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: _handleTap,
      child: Container(
        child: Center(
          child: Text(
            _active ? 'Active' : 'Inactive',
            style: const TextStyle(fontSize: 32.0, color: Colors.white),
          ),
        ),
        width: 200.0,
        height: 200.0,
        decoration: BoxDecoration(
          color: _active ? Colors.lightGreen[700] : Colors.grey[600],
        ),
      ),
    );
  }
}

//------------------------- MyApp ----------------------------------

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Flutter Demo'),
        ),
        body: const Center(
          child: TapboxA(),
        ),
      ),
    );
  }
}

The parent widget manages the widget’s state

一般来说父 widget 管理状态并告诉其子 widget 何时更新通常是最合适的。例如，IconButton 允许您将图标视为可点按的按钮。 IconButton 是一个无状态 widget，因为我们认为父 widget 需要知道该按钮是否被点击来采取相应的处理。

Often it makes the most sense for the parent widget to manage the state and tell its child widget when to update. For example, IconButton allows you to treat an icon as a tappable button. IconButton is a stateless widget because we decided that the parent widget needs to know whether the button has been tapped, so it can take appropriate action.

在以下示例中，TapboxB 通过回调将其状态到其父类。由于 TapboxB 不管理任何状态，因此它继承自 StatelessWidget。

In the following example, TapboxB exports its state to its parent through a callback. Because TapboxB doesn’t manage any state, it subclasses StatelessWidget.

ParentWidgetState 类：

The ParentWidgetState class:

为 TapboxB 管理 _active 状态；
Manages the _active state for TapboxB.
实现 _handleTapboxChanged()，当盒子被点击时调用的方法；
Implements _handleTapboxChanged(), the method called when the box is tapped.
当状态改变时，调用 setState() 更新 UI。
When the state changes, calls setState() to update the UI.

TapboxB 类：

The TapboxB class:

继承 StatelessWidget 类，因为所有状态都由其父 widget 处理；
Extends StatelessWidget because all state is handled by its parent.
当检测到点击时，它会通知父 widget。
When a tap is detected, it notifies the parent.

import 'package:flutter/material.dart';

// ParentWidget manages the state for TapboxB.

//------------------------ ParentWidget --------------------------------

class ParentWidget extends StatefulWidget {
  const ParentWidget({Key? key}) : super(key: key);

  @override
  _ParentWidgetState createState() => _ParentWidgetState();
}

class _ParentWidgetState extends State<ParentWidget> {
  bool _active = false;

  void _handleTapboxChanged(bool newValue) {
    setState(() {
      _active = newValue;
    });
  }

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      child: TapboxB(
        active: _active,
        onChanged: _handleTapboxChanged,
      ),
    );
  }
}

//------------------------- TapboxB ----------------------------------

class TapboxB extends StatelessWidget {
  const TapboxB({
    Key? key,
    this.active = false,
    required this.onChanged,
  }) : super(key: key);

  final bool active;
  final ValueChanged<bool> onChanged;

  void _handleTap() {
    onChanged(!active);
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: _handleTap,
      child: Container(
        child: Center(
          child: Text(
            active ? 'Active' : 'Inactive',
            style: const TextStyle(fontSize: 32.0, color: Colors.white),
          ),
        ),
        width: 200.0,
        height: 200.0,
        decoration: BoxDecoration(
          color: active ? Colors.lightGreen[700] : Colors.grey[600],
        ),
      ),
    );
  }
}

混搭管理

A mix-and-match approach

对于一些 widget 来说，混搭管理的方法最合适的。在这种情况下，有状态的 widget 自己管理一些状态，同时父 widget 管理其他方面的状态。

For some widgets, a mix-and-match approach makes the most sense. In this scenario, the stateful widget manages some of the state, and the parent widget manages other aspects of the state.

在 TapboxC 示例中，点击时，盒子的周围会出现一个深绿色的边框。点击时，边框消失，盒子的颜色改变。 TapboxC 将其 _active 状态导出到其父 widget 中，但在内部管理其 _highlight 状态。这个例子有两个状态对象 _ParentWidgetState 和 _TapboxCState。

In the TapboxC example, on tap down, a dark green border appears around the box. On tap up, the border disappears and the box’s color changes. TapboxC exports its _active state to its parent but manages its _highlight state internally. This example has two State objects, _ParentWidgetState and _TapboxCState.

_ParentWidgetState 对象：

The _ParentWidgetState object:

管理_active 状态。
Manages the _active state.
实现 _handleTapboxChanged()，此方法在盒子被点击时调用。
Implements _handleTapboxChanged(), the method called when the box is tapped.
当点击盒子并且 _active 状态改变时调用 setState() 来更新 UI。
Calls setState() to update the UI when a tap occurs and the _active state changes.

_TapboxCState 对象:

The _TapboxCState object:

管理 _highlight state。
Manages the _highlight state.
GestureDetector 监听所有 tap 事件。当用户点下时，它添加高亮（深绿色边框）；当用户释放时，会移除高亮。
The GestureDetector listens to all tap events. As the user taps down, it adds the highlight (implemented as a dark green border). As the user releases the tap, it removes the highlight.
当按下、抬起、或者取消点击时更新 _highlight 状态，调用 setState() 更新UI。
Calls setState() to update the UI on tap down, tap up, or tap cancel, and the _highlight state changes.
当点击时，widget 属性将状态的改变传递给父 widget 并进行合适的操作。
On a tap event, passes that state change to the parent widget to take appropriate action using the widget property.

import 'package:flutter/material.dart';

//---------------------------- ParentWidget ----------------------------

class ParentWidget extends StatefulWidget {
  const ParentWidget({Key? key}) : super(key: key);

  @override
  _ParentWidgetState createState() => _ParentWidgetState();
}

class _ParentWidgetState extends State<ParentWidget> {
  bool _active = false;

  void _handleTapboxChanged(bool newValue) {
    setState(() {
      _active = newValue;
    });
  }

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      child: TapboxC(
        active: _active,
        onChanged: _handleTapboxChanged,
      ),
    );
  }
}

//----------------------------- TapboxC ------------------------------

class TapboxC extends StatefulWidget {
  const TapboxC({
    Key? key,
    this.active = false,
    required this.onChanged,
  }) : super(key: key);

  final bool active;
  final ValueChanged<bool> onChanged;

  @override
  _TapboxCState createState() => _TapboxCState();
}

class _TapboxCState extends State<TapboxC> {
  bool _highlight = false;

  void _handleTapDown(TapDownDetails details) {
    setState(() {
      _highlight = true;
    });
  }

  void _handleTapUp(TapUpDetails details) {
    setState(() {
      _highlight = false;
    });
  }

  void _handleTapCancel() {
    setState(() {
      _highlight = false;
    });
  }

  void _handleTap() {
    widget.onChanged(!widget.active);
  }

  @override
  Widget build(BuildContext context) {
    // This example adds a green border on tap down.
    // On tap up, the square changes to the opposite state.
    return GestureDetector(
      onTapDown: _handleTapDown, // Handle the tap events in the order that
      onTapUp: _handleTapUp, // they occur: down, up, tap, cancel
      onTap: _handleTap,
      onTapCancel: _handleTapCancel,
      child: Container(
        child: Center(
          child: Text(widget.active ? 'Active' : 'Inactive',
              style: const TextStyle(fontSize: 32.0, color: Colors.white)),
        ),
        width: 200.0,
        height: 200.0,
        decoration: BoxDecoration(
          color: widget.active ? Colors.lightGreen[700] : Colors.grey[600],
          border: _highlight
              ? Border.all(
                  color: Colors.teal[700]!,
                  width: 10.0,
                )
              : null,
        ),
      ),
    );
  }
}

另一种实现可能会将高亮状态导出到父 widget，同时保持 active 状态为内部，但如果你要求某人使用该 TapBox，他们可能会抱怨说没有多大意义。开发人员只会关心该框是否处于活动状态。开发人员可能不在乎高亮显示是如何管理的，并且倾向于让 TapBox 处理这些细节。

An alternate implementation might have exported the highlight state to the parent while keeping the active state internal, but if you asked someone to use that tap box, they’d probably complain that it doesn’t make much sense. The developer cares whether the box is active. The developer probably doesn’t care how the highlighting is managed, and prefers that the tap box handles those details.

其他交互式 widgets

Other interactive widgets

Flutter 提供各种按钮和类似的交互式 widget。这些 widget 中的大多数都实现了 Material Design guidelines，它们定义了一组具有质感的 UI 组件。

Flutter offers a variety of buttons and similar interactive widgets. Most of these widgets implement the Material Design guidelines, which define a set of components with an opinionated UI.

如果你愿意，你可以使用 GestureDetector 来给任何自定义 widget 添加交互性。你可以在管理状态中找到 GestureDetector 的示例。同时你也可以在 Flutter cookbook 的处理点击中学习更多关于 GestureDetector 的内容。

If you prefer, you can use GestureDetector to build interactivity into any custom widget. You can find examples of GestureDetector in Managing state. Learn more about the GestureDetector in Handle taps, a recipe in the Flutter cookbook.

当你需要交互性时，最容易的是使用预制的 widget。这是预置 widget 部分列表:

When you need interactivity, it’s easiest to use one of the prefabricated widgets. Here’s a partial list:

标准 widgets

Standard widgets

Material 组件

Material Components

资源

Resources

以下资源可能会在给您的应用添加交互的时候有所帮助。

The following resources might help when adding interactivity to your app.

手势，Flutter 实用教程里的一个小节。

Gestures, a section in the Flutter cookbook.

处理手势，widgets 介绍文档中一部分
如何创建一个按钮并使其响应用户动作。

Handling gestures, a section in Introduction to widgets
How to create a button and make it respond to input.

点击、拖动和其他手势
Flutter 手势机制的描述。

Gestures in Flutter
A description of Flutter’s gesture mechanism.

Flutter API 文档
所有 Flutter API 的参考文档。

Flutter API documentation
Reference documentation for all of the Flutter libraries.

Flutter Gallery 应用，代码仓库
一个 Demo 应用程序，展示了许多 Material 和其他 Flutter 功能。

Flutter Gallery running app, repo
Demo app showcasing many Material components and other Flutter features.

Flutter 的分层设计 (视频)
此视频包含有关有状态和无状态 widget 的信息。由 Google 工程师 Ian Hickson 讲解。

Flutter’s Layered Design (video)
This video includes information about state and stateless widgets. Presented by Google engineer, Ian Hickson.

添加资源和图片

Flutter 应用程序包含代码和 assets（也为资源）。资源是被打包到应用程序安装包中，可以在运行时访问的一种文件。常见的资源类型包括静态数据（例如 JSON 文件），配置文件，图标和图片（JPEG，WebP，GIF，动画 WebP / GIF，PNG，BMP 和 WBMP）。

Flutter apps can include both code and assets (sometimes called resources). An asset is a file that is bundled and deployed with your app, and is accessible at runtime. Common types of assets include static data (for example, JSON files), configuration files, icons, and images (JPEG, WebP, GIF, animated WebP/GIF, PNG, BMP, and WBMP).

指定资源

Specifying assets

Flutter 使用 pubspec.yaml 文件，位于项目根目录，来识别应用程序所需的资源。

Flutter uses the pubspec.yaml file, located at the root of your project, to identify assets required by an app.

下面举个例子:

Here is an example:

flutter:
  assets:
    - assets/my_icon.png
    - assets/background.png

如果要包含一个目录下的所有 assets，需要在目录名称的结尾加上 /：

To include all assets under a directory, specify the directory name with the / character at the end:

flutter:
  assets:
    - directory/
    - directory/subdirectory/

资源打包

Asset bundling

该 assets 部分的 flutter 部分需要指定包含在应用程序中的文件。每个资源都通过相对于 pubspec.yaml 文件所在位置的路径进行标识。资源的声明顺序是无关紧要的。资源的实际目录可以是任意文件夹（在第一个样例中是 assets，其他的是 directory）

The assets subsection of the flutter section specifies files that should be included with the app. Each asset is identified by an explicit path (relative to the pubspec.yaml file) where the asset file is located. The order in which the assets are declared doesn’t matter. The actual directory name used (assets in first example or directory in the above example) doesn’t matter.

在一次构建中，Flutter 将 assets 放到 asset bundle 的特殊归档中，以便应用程序在运行时读取它们。

During a build, Flutter places assets into a special archive called the asset bundle that apps read from at runtime.

资源变体

Asset variants

构建过程支持 asset 变体：不同版本的资源可能会显示在不同的上下文中。在 pubspec.yaml 的 assets 部分中指定的资源路径，会在构建过程中，查找同级子目录中相同名称的任何文件。这些文件会与指定的资源一起被打包在资源 bundle 中。

The build process supports the notion of asset variants: different versions of an asset that might be displayed in different contexts. When an asset’s path is specified in the assets section of pubspec.yaml, the build process looks for any files with the same name in adjacent subdirectories. Such files are then included in the asset bundle along with the specified asset.

例如，你的应用程序目录中有以下文件：

For example, if you have the following files in your application directory:

.../pubspec.yaml
.../graphics/my_icon.png
.../graphics/background.png
.../graphics/dark/background.png
...etc.

…同时 pubspec.yaml 文件包含：

And your pubspec.yaml file contains the following:

flutter:
  assets:
    - graphics/background.png

那么这两个图片： graphics/background.png 和 graphics/dark/background.png 将被打包在你的资源 bundle 中。前者被称为是 main asset，后者被称为是一种变体（variant）。

Then both graphics/background.png and graphics/dark/background.png are included in your asset bundle. The former is considered the main asset, while the latter is considered a variant.

如果指定的是 graphics 目录：

If, on the other hand, the graphics directory is specified:

flutter:
  assets:
    - graphics/

… 那么 graphics/my_icon.png， graphics/background.png 和 graphics/dark/background.png 同时被包含。

Then the graphics/my_icon.png, graphics/background.png and graphics/dark/background.png files are also included.

在选择当前设备分辨率的图片时，Flutter 会使用资源变体；见下文。将来，这种机制可能会扩展到本地化、阅读提示等方面。

Flutter uses asset variants when choosing resolution-appropriate images. In the future, this mechanism might be extended to include variants for different locales or regions, reading directions, and so on.

加载 assets

Loading assets

你的应用程序可以通过 AssetBundle 对象访问其资源。

Your app can access its assets through an AssetBundle object.

Asset bundle 通过指定一个逻辑键（key），允许你读取 string/text（loadString）和 image/binary（load）。在编译期间，这个逻辑键（key）会映射在 pubspec.yaml 中指定的资源路径。

The two main methods on an asset bundle allow you to load a string/text asset (loadString()) or an image/binary asset (load()) out of the bundle, given a logical key. The logical key maps to the path to the asset specified in the pubspec.yaml file at build time.

加载文本 assets

Loading text assets

每个 Flutter 应用程序都有一个 rootBundle 对象，可以轻松访问主资源 bundle 。还可以直接使用 package:flutter/services.dart 中全局静态的 rootBundle 来加载资源。

Each Flutter app has a rootBundle object for easy access to the main asset bundle. It is possible to load assets directly using the rootBundle global static from package:flutter/services.dart.

但是，如果获取当前 BuildContext 的 AssetBundle，建议使用 DefaultAssetBundle。这种方式不是使用应用程序构建的默认资源 bundle，而是让父级 widget 在运行时替换的不同的 AssetBundle，这对于本地化或测试场景很有用。

However, it’s recommended to obtain the AssetBundle for the current BuildContext using DefaultAssetBundle, rather than the default asset bundle that was built with the app; this approach enables a parent widget to substitute a different AssetBundle at run time, which can be useful for localization or testing scenarios.

通常，你可以从应用程序运行时的 rootBundle 中，间接使用 DefaultAssetBundle.of() 来加载资源（例如 JSON 文件）。

Typically, you’ll use DefaultAssetBundle.of() to indirectly load an asset, for example a JSON file, from the app’s runtime rootBundle.

在 Widget 上下文之外，或 AssetBundle 的句柄不可用时，你可以使用 rootBundle 直接加载这些 assets，例如：

Outside of a Widget context, or when a handle to an AssetBundle is not available, you can use rootBundle to directly load such assets. For example:

import 'package:flutter/services.dart' show rootBundle;

Future<String> loadAsset() async {
  return await rootBundle.loadString('assets/config.json');
}

加载图片

Loading images

Flutter 可以为当前设备加载适合其分辨率的图像。

Flutter can load resolution-appropriate images for the current device pixel ratio.

声明分辨率相关的图片 assets

Declaring resolution-aware image assets

AssetImage 可以将逻辑请求资源映射到最接近当前设备像素比的资源。为了使这种映射起作用，应该根据特定的目录结构来保存资源：

AssetImage understands how to map a logical requested asset onto one that most closely matches the current device pixel ratio. In order for this mapping to work, assets should be arranged according to a particular directory structure:

.../image.png
.../Mx/image.png
.../Nx/image.png
...etc.

…其中 M 和 N 是数字标识符，对应于其中包含的图像的分辨率，换句话说，它们指定不同设备像素比例的图片。

Where M and N are numeric identifiers that correspond to the nominal resolution of the images contained within. In other words, they specify the device pixel ratio that the images are intended for.

主资源默认对应于 1.0 倍的分辨率图片。比如下面的图片 my_icon.png：

The main asset is assumed to correspond to a resolution of 1.0. For example, consider the following asset layout for an image named my_icon.png:

.../my_icon.png
.../2.0x/my_icon.png
.../3.0x/my_icon.png

而在设备像素比率为 1.8 的设备上，对应是 .../2.0x/my_icon.png 。如果是 2.7 的设备像素比，对应是 .../3.0x/my_icon.png 。

On devices with a device pixel ratio of 1.8, the asset .../2.0x/my_icon.png is chosen. For a device pixel ratio of 2.7, the asset .../3.0x/my_icon.png is chosen.

如果在 Image widget 上未指定渲染图像的宽度和高度，通常会扩展资源来保证与主资源相同的屏幕空间量，并不是相同的物理像素，只是分辨率更高。换句话说，.../my_icon.png 是 72 px 乘 72 px，那么 .../3.0x/my_icon.png 应该是 216 px 乘 216 px；但如果未指定宽度和高度，它们都将渲染为 72 px 乘 72 px（以逻辑像素为单位）。

If the width and height of the rendered image are not specified on the Image widget, the nominal resolution is used to scale the asset so that it occupies the same amount of screen space as the main asset would have, just with a higher resolution. That is, if .../my_icon.png is 72px by 72px, then .../3.0x/my_icon.png should be 216px by 216px; but they both render into 72px by 72px (in logical pixels), if width and height are not specified.

在 pubspec.yaml 中资源部分的每一项都应与实际文件相对应，除过主资源节点。当主资源缺少某个文件时，会按分辨率从低到高的顺序去选择，也就是说 1x 中没有的话会在 2x 中找，2x 中还没有的话就在 3x 中找。该条目需要在 pubspec.yaml 中指定。

Each entry in the asset section of the pubspec.yaml should correspond to a real file, with the exception of the main asset entry. If the main asset entry doesn’t correspond to a real file, then the asset with the lowest resolution is used as the fallback for devices with device pixel ratios below that resolution. The entry should still be included in the pubspec.yaml manifest, however.

加载 images

Loading images

加载图片，请在 widget 的 build 方法中使用 AssetImage 类。

To load an image, use the AssetImage class in a widget’s build() method.

例如，你的应用程序可以从上面的资源声明中加载背景图片：

For example, your app can load the background image from the asset declarations above:

return const Image(image: AssetImage('graphics/background.png'));

使用默认的资源 bundle 加载资源时，系统会自动处理分辨率等。（如果你使用一些更低级别的类，如 ImageStream 或 ImageCache，你需要注意 scale 相关的参数)。

Anything using the default asset bundle inherits resolution awareness when loading images. (If you work with some of the lower level classes, like ImageStream or ImageCache, you’ll also notice parameters related to scale.)

依赖包中的资源图片

Asset images in package dependencies

加载依赖 package 中的图像，必须给 AssetImage 提供 package 参数。

To load an image from a package dependency, the package argument must be provided to AssetImage.

例如，你的应用程序依赖于一个名为 my_icons 的 package，它的目录结构如下：

For instance, suppose your application depends on a package called my_icons, which has the following directory structure:

.../pubspec.yaml
.../icons/heart.png
.../icons/1.5x/heart.png
.../icons/2.0x/heart.png
...etc.

然后加载 image, 使用：

To load the image, use:

return const AssetImage('icons/heart.png', package: 'my_icons');

package 使用本身的 Assets 也需要加上 package 参数来获取。

Assets used by the package itself should also be fetched using the package argument as above.

打包 assets

Bundling of package assets

如果期望的资源文件被指定在 package 的 pubspec.yaml 文件中，它会被自动打包到应用程序中。特别是，package 本身使用的资源必须在 pubspec.yaml 中指定。

If the desired asset is specified in the pubspec.yaml file of the package, it’s bundled automatically with the application. In particular, assets used by the package itself must be specified in its pubspec.yaml.

package 也可以选择在其 lib/ 文件夹中包含未在 pubspec.yaml 文件中声明的资源。在这种情况下，对于要打包的图片，应用程序必须在 pubspec.yaml 中指定包含哪些图像。例如，一个名为 fancy_backgrounds 的包，可能包含以下文件：

A package can also choose to have assets in its lib/ folder that are not specified in its pubspec.yaml file. In this case, for those images to be bundled, the application has to specify which ones to include in its pubspec.yaml. For instance, a package named fancy_backgrounds could have the following files:

.../lib/backgrounds/background1.png
.../lib/backgrounds/background2.png
.../lib/backgrounds/background3.png

总而言之，要包含第一张图像，必须在 pubspec.yaml 的 assets 部分中声明它：

To include, say, the first image, the pubspec.yaml of the application should specify it in the assets section:

flutter:
  assets:
    - packages/fancy_backgrounds/backgrounds/background1.png

lib/ 是隐含的，所以它不应该包含在资源路径中。

The lib/ is implied, so it should not be included in the asset path.

Sharing assets with the underlying platform

在不同平台读取 Flutter assets， Android 是通过 AssetManager，iOS 是 NSBundle。

Flutter assets are readily available to platform code using the AssetManager on Android and NSBundle on iOS.

在 Android 中加载 Flutter 资源文件

Loading Flutter assets in Android

在 Android 平台上，assets 通过 AssetManager API 读取。通过 PluginRegistry.Registrar 的 lookupKeyForAsset 方法，或者 FlutterView 的 getLookupKeyForAsset 方法来获取文件路径，然后 AssetManager 的 openFd 根据文件路径得到文件描述符。开发插件时可以使用 PluginRegistry.Registrar，而开发应用程序使用平台视图时，FlutterView 是最好的选择。

On Android the assets are available through the AssetManager API. The lookup key used in, for instance openFd, is obtained from lookupKeyForAsset on PluginRegistry.Registrar or getLookupKeyForAsset on FlutterView. PluginRegistry.Registrar is available when developing a plugin while FlutterView would be the choice when developing an app including a platform view.

举个例子，假设你在 pubspec.yaml 中这样指定：

As an example, suppose you have specified the following in your pubspec.yaml

flutter:
  assets:
    - icons/heart.png

在你的 Flutter 应用程序对应以下结构。

This reflects the following structure in your Flutter app.

.../pubspec.yaml
.../icons/heart.png
...etc.

想要在 Java 插件中访问 icons/heart.png；

To access icons/heart.png from your Java plugin code, do the following:

AssetManager assetManager = registrar.context().getAssets();
String key = registrar.lookupKeyForAsset("icons/heart.png");
AssetFileDescriptor fd = assetManager.openFd(key);

在 iOS 中加载 Flutter 资源文件

Loading Flutter assets in iOS

在 iOS 平台上，assets 资源文件通过 mainBundle 读取。通过 pathForResource:ofType: 的 lookupKeyForAsset 或者 lookupKeyForAsset:fromPackage: 方法获取文件路径，同样，FlutterViewController 的 lookupKeyForAsset: 或者 lookupKeyForAsset:fromPackage: 方法也可以获取文件路径。开发插件时可以使用 FlutterPluginRegistrar，而开发应用程序使用平台视图时， FlutterViewController 是最好的选择。

On iOS the assets are available through the mainBundle. The lookup key used in, for instance pathForResource:ofType:, is obtained from lookupKeyForAsset or lookupKeyForAsset:fromPackage: on FlutterPluginRegistrar, or lookupKeyForAsset: or lookupKeyForAsset:fromPackage: on FlutterViewController. FlutterPluginRegistrar is available when developing a plugin while FlutterViewController would be the choice when developing an app including a platform view.

举个例子，假设你的 Flutter 配置和上面一样。

As an example, suppose you have the Flutter setting from above.

要在 Objective-C 插件中访问 icons/heart.png：

To access icons/heart.png from your Objective-C plugin code you would do the following:

NSString* key = [registrar lookupKeyForAsset:@"icons/heart.png"];
NSString* path = [[NSBundle mainBundle] pathForResource:key ofType:nil];

这有一个更完整的实例可以理解 Flutter 的应用：video_player plugin。

For a more complete example, see the implementation of the Flutter video_player plugin on pub.dev.

pub.dev 上的 ios_platform_images plugin 将这些逻辑封装成方便的类别。它允许编写：

The ios_platform_images plugin on pub.dev wraps up this logic in a convenient category. You fetch an image as follows:

Objective-C:

[UIImage flutterImageWithName:@"icons/heart.png"];

Swift:

UIImage.flutterImageNamed("icons/heart.png")

在 Flutter 中加载 iOS 的图片

Loading iOS images in Flutter

When implementing Flutter by adding it to an existing iOS app, you might have images hosted in iOS that you want to use in Flutter. To accomplish that, use the ios_platform_images plugin available on pub.dev.

平台 assets

Platform assets

某些场景可以直接在平台项目中使用 assets。以下是在 Flutter 框架加载并运行之前使用资源的两种常见情况。

There are other occasions to work with assets in the platform projects directly. Below are two common cases where assets are used before the Flutter framework is loaded and running.

更新桌面图标

Updating the app icon

更新你的 Flutter 应用程序启动图标，和原生 Android 或 iOS 应用程序中更新启动图标的方法相同。

Updating a Flutter application’s launch icon works the same way as updating launch icons in native Android or iOS applications.

Android

在 Flutter 项目的根目录中，导航到 .../android/app/src/main/res 路径。各种位图资源文件夹，比如 mipmap-hdpi，已包含占位符图像 ic_launcher.png。只需按照 Android 开发者指南中的说明，将其替换为所需的资源，并遵守每种屏幕分辨率的建议图标大小标准。

In your Flutter project’s root directory, navigate to .../android/app/src/main/res. The various bitmap resource folders such as mipmap-hdpi already contain placeholder images named ic_launcher.png. Replace them with your desired assets respecting the recommended icon size per screen density as indicated by the Android Developer Guide.

iOS

在你的 Flutter 项目的根目录中，导航到 .../ios/Runner 路径。该目录中 Assets.xcassets/AppIcon.appiconset已经包含占位符图片，只需将它们替换为适当大小的图片，并且根据 iOS 开发指南，文件名称保持不变。

In your Flutter project’s root directory, navigate to .../ios/Runner. The Assets.xcassets/AppIcon.appiconset directory already contains placeholder images. Replace them with the appropriately sized images as indicated by their filename as dictated by the Apple Human Interface Guidelines. Keep the original file names.

更新启动图

Updating the launch screen

Launch screen

在 Flutter 框架加载时，Flutter 会使用原生平台机制绘制启动页。此启动页将持续到 Flutter 渲染应用程序的第一帧。

Flutter also uses native platform mechanisms to draw transitional launch screens to your Flutter app while the Flutter framework loads. This launch screen persists until Flutter renders the first frame of your application.

Android

将启动屏幕「splash screen」添加到你的 Flutter 应用程序，请导航至 .../android/app/src/main 路径。在 res/drawable/launch_background.xml 文件中，通过使用图层列表 XML 来实现自定义启动页。现有模板提供了一个示例，用于将图片添加到白色启动页的中间（注释代码中）。你也可以取消注释使用可绘制对象资源来实现预期效果。

To add a “splash screen” to your Flutter application, navigate to .../android/app/src/main. In res/drawable/launch_background.xml, use this layer list drawable XML to customize the look of your launch screen. The existing template provides an example of adding an image to the middle of a white splash screen in commented code. You can uncomment it or use other drawables to achieve the intended effect.

更多详细信息，请查看在 Android 应用中添加闪屏页与启动页。

For more details, see Adding a splash screen to your mobile app.

iOS

将图片添加到启动屏幕「splash screen」的中心，请导航至 .../ios/Runner 路径。在 Assets.xcassets/LaunchImage.imageset ，拖入图片，并命名为 LaunchImage.png， LaunchImage@2x.png，LaunchImage@3x.png。如果你使用不同的文件名，那你还必须更新同一目录中的 Contents.json 文件中对应的名称。

To add an image to the center of your “splash screen”, navigate to .../ios/Runner. In Assets.xcassets/LaunchImage.imageset, drop in images named LaunchImage.png, LaunchImage@2x.png, LaunchImage@3x.png. If you use different filenames, update the Contents.json file in the same directory.

你也可以通过打开 .../ios/Runner.xcworkspace ，完全自定义 storyboard。在 Project Navigator 中导航到 Runner/Runner ，然后打开 Assets.xcassets 拖入图片，或者在 LaunchScreen.storyboard 中使用 Interface Builder 进行自定义。

You can also fully customize your launch screen storyboard in Xcode by opening .../ios/Runner.xcworkspace. Navigate to Runner/Runner in the Project Navigator and drop in images by opening Assets.xcassets or do any customization using the Interface Builder in LaunchScreen.storyboard.

Adding launch icons in Xcode

更多详细信息，请查看在 Android 应用中添加闪屏页与启动页。

For more details, see Adding a splash screen to your mobile app.

路由和导航

Flutter 有一个命令式路由机制，即 Navigator 组件，还有一个更为惯用的声明式路由机制（类似于 widget 中使用的 build 方法），即 Router 组件。

Flutter has an imperative routing mechanism, the Navigator widget, and a more idiomatic declarative routing mechanism (which is similar to build methods as used with widgets), the Router widget.

这两个系统可以一起使用（事实上，声明式系统是使用命令式系统构建的）。

The two systems can be used together (indeed, the declarative system is built using the imperative system).

对于小型应用程序来说，通常只需通过 MaterialApp 构造函数中的 MaterialApp.routes 属性，加以使用 Navigator API，就可以很好地提供服务。

Typically, small applications are served well by just using the Navigator API, via the MaterialApp constructor’s MaterialApp.routes property.

要了解 Navigator 及其命令式 API，参阅 Flutter 教程中的 Navigator 教程和 Navigator API 文档。

To learn about Navigator and its imperative API, see the Navigation recipes in the Flutter cookbook, and the Navigator API docs.

通过 MaterialApp.router 构造函数，Router API 可以更好地为复杂应用程序服务。它需要更多的前期工作来描述如何解析应用程序的复杂路由，以及如何将应用程序的状态映射到页面集合，但从长远的角度来看会使路由的控制更具表现力。

More elaborate applications are usually better served by the Router API, via the MaterialApp.router constructor. This requires some more up-front work to describe how to parse deep links for your application and how to map the application state to the set of active pages, but is more expressive on the long run.

要了解 Router 和声明式方法，参阅学习 Flutter 的新导航和路由系统和 Router API 文档。

To learn about Router and the declarative approach, see Learning Flutter’s new navigation and routing system, and the Router API docs.

Deep linking

Enable deep linking on Android
Test on Android emulator
Enable deep linking on iOS
Test on iOS simulator
Migrating from plugin-based deep linking
Behavior
See also

Flutter supports deep linking on iOS, Android, and web browsers. Opening a URL displays that screen in your app. With the following steps, you can launch and display routes by using named routes (either with the routes parameter or onGenerateRoute), or by using the Router widget.

If you’re running the app in a web browser, there’s no additional setup required. Route paths are handled in the same way as an iOS or Android deep link. By default, web apps read the deep link path from the url fragment using the pattern: /#/path/to/app/screen, but this can be changed by configuring the URL strategy for your app.

To follow along, clone the Navigation and Routing in flutter/samples.

Enable deep linking on Android

Add a metadata tag and intent filter to AndroidManifest.xml inside the <activity> tag with the ".MainActivity" name:

<!-- Deep linking -->
<meta-data android:name="flutter_deeplinking_enabled" android:value="true" />
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="http" android:host="flutterbooksample.com" />
    <data android:scheme="https" />
</intent-filter>

A full restart is required to apply these changes.

Test on Android emulator

To test with an Android emulator, give the adb command an intent where the host name matches the name defined in AndroidManifest.xml:

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "http://flutterbooksample.com/book/1"

For more details, see the Verify Android App Links documentation in the Android docs.

Enable deep linking on iOS

Add two new keys to Info.plist in the ios/Runner directory:

<key>FlutterDeepLinkingEnabled</key>
<true/>
<key>CFBundleURLTypes</key>
<array>
    <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>flutterbooksample.com</string>
    <key>CFBundleURLSchemes</key>
    <array>
    <string>customscheme</string>
    </array>
    </dict>
</array>

The CFBundleURLName is a unique URL used to distinguish your app from others that use the same scheme. The scheme (customscheme://) can also be unique.

A full restart is required to apply these changes.

Test on iOS simulator

Use the xcrun command to test on the iOS Simulator:

xcrun simctl openurl booted customscheme://flutterbooksample.com/book/1

Migrating from plugin-based deep linking

If you have written a plugin to handle deep links, as described in “Deep Links and Flutter applications” on Medium, it will continue to work until you opt-in to this behavior by adding FlutterDeepLinkingEnabled to Info.plist or flutter_deeplinking_enabled to AndroidManifest.xml, respectively.

Behavior

The behavior varies slightly based on the platform and whether the app is launched and running.

Platform / Scenario	Using Navigator	Using Router
iOS (not launched)	App gets initialRoute (“/”) and a short time after gets a pushRoute	App gets initialRoute (“/”) and a short time after uses the RouteInformationParser to parse the route and call RouterDelegate.setNewRoutePath, which configures the Navigator with the corresponding Page.
Android - (not launched)	App gets initialRoute containing the route (“/deeplink”)	App gets initialRoute (“/deeplink”) and passes it to the RouteInformationParser to parse the route and call RouterDelegate.setNewRoutePath, which configures the Navigator with the corresponding Pages.
iOS (launched)	pushRoute is called	Path is parsed, and the Navigator is configured with a new set of Pages.
Android (launched)	pushRoute is called	Path is parsed, and the Navigator is configured with a new set of Pages.

After upgrading to the Router widget, your app has the ability to replace the current set of pages when a new deep link is opened while the app is running.

配置 Web 应用的 URL 策略

配置 URL 策略
Configuring the URL strategy
将 Flutter 应用部署在子目录下
Hosting a Flutter app at a non-root location

Flutter Web 应用支持两种基于 URL 的路由的配置方式：

Flutter web apps support two ways of configuring URL-based navigation on the web:

Hash（默认）
路径使用 # + 锚点标识符读写，例如：flutterexample.dev/#/path/to/screen。

Hash (default)
Paths are read and written to the hash fragment. For example, flutterexample.dev/#/path/to/screen.

Path
路径使用非 # 读写，例如：flutterexample.dev/path/to/screen。

Path
Paths are read and written without a hash. For example, flutterexample.dev/path/to/screen.

使用 setUrlStrategy API 设置 HashUrlStrategy 或者 PathUrlStrategy。

These are set using the setUrlStrategy API with either a HashUrlStrategy or PathUrlStrategy.

配置 URL 策略

Configuring the URL strategy

setUrlStrategy API 只能在 Web 平台使用。下方的内容将介绍如何在 Web 平台下（仅在 Web 平台可用）使用条件引入的方式来调用此方法。

The setUrlStrategy API can only be called on the web. The following instructions show how to use a conditional import to call this function on the web, but not on other platforms.

Include the flutter_web_plugins package and call the setUrlStrategy function before your app runs:引入 flutter_web_plugins package，并在你的应用启动前调用 setUrlStrategy 方法：
```
  dependencies:
    flutter_web_plugins:
      sdk: flutter
```
Create a lib/configure_nonweb.dart file with the following code:创建如下的 lib/configure_nonweb.dart 文件：
```
  void configureApp() {
    // No-op.
  }
```

Create a lib/configure_web.dart file with the following code:创建如下的 lib/configure_web.dart 文件：

  import 'package:flutter_web_plugins/flutter_web_plugins.dart';

  void configureApp() {
    setUrlStrategy(PathUrlStrategy());
  }

Open `lib/main.dart` and conditionally import `configure_web.dart` when the `html` package is available, or `configure_nonweb.dart` when it isn't:

打开 `lib/main.dart`，当 `html` 包可用时，使用条件引入的方式引入 `configure_web.dart`，否则引入 `configure_nonweb.dart`：
```
  import 'package:flutter/material.dart';
  import 'configure_nonweb.dart' if (dart.library.html) 'configure_web.dart';

  void main() {
    configureApp();
  runApp(MyApp());
  }
```

将 Flutter 应用部署在子目录下

Hosting a Flutter app at a non-root location

更新 web/index.html 中的 <base href="/"> 标签为你的应用部署路径。例如：如果你期望将 Flutter 应用部署在 myapp.dev/flutter_app，则更改此标签为 <base href="/flutter_app">。

Update the <base href="/"> tag in web/index.html to the path where your app is hosted. For example, to host your Flutter app at myapp.dev/flutter_app, change this tag to <base href="/flutter_app/">.

动画效果介绍

选择一种实现方式
Choosing an approach
Codelabs, 教程和文章
Codelabs, tutorials, and articles
Animation types
- 补间动画
  Tween animation
- 基于物理基础的动画
  Physics-based animation
预置动画
Pre-canned animations
常见动画模式
Common animation patterns
其他资源
Other resources

Well-designed animations make a UI feel more intuitive, contribute to the slick look and feel of a polished app, and improve the user experience. Flutter’s animation support makes it easy to implement a variety of animation types. Many widgets, especially Material widgets, come with the standard motion effects defined in their design spec, but it’s also possible to customize these effects.

选择一种实现方式

Choosing an approach

在 Flutter 中创建动画可以有多种不同实现方式。那么，究竟哪种才是最适合你的呢？为了帮助你更好的理解它，你可以观看下面的视频，如何在 Flutter 中选择合适的动画 Widget （同时也发布了一篇配套文章。）

There are different approaches you can take when creating animations in Flutter. Which approach is right for you? To help you decide, check out the video, How to choose which Flutter Animation Widget is right for you? (Also published as a companion article.)

（若想要深入了解它的决策流程，请观看在 Flutter Europe 社区账号发布的在 Flutter 中使用动画的正确选择）视频。

(To dive deeper into the decision process, watch the Animations in Flutter done right video, presented at Flutter Europe.)

正如视频中说的那样，下面的决策树将帮助你挑选实现 Flutter 动画的正确方式：

As shown in the video, the following decision tree helps you decide what approach to use when implementing a Flutter animation:

The animation decision tree

如果内置的隐式动画（最简单的动画）已经能够满足你的需求，请观看隐式动画基础。（同时也发布了一篇配套文章。）

If a pre-packaged implicit animation (the easiest animation to implement) suits your needs, watch Animation basics with implicit animations. (Also published as a companion article.)

要创建一个自定义的隐式动画，请观看使用 TweenAnimationBuilder 创建独特的隐式动画。（同时也发布了一篇配套文章。）

To create a custom implicit animation, watch Creating your own custom implicit animations with TweenAnimationBuilder. (Also published as a companion article.)

要创建显式动画（手动控制，而不是让框架控制），你可以使用内置的其中一个显式动画类来实现。更多有关信息，请观看使用内置显式动画。（同时也发布了一篇配套文章。）

To create an explicit animation (where you control the animation, rather than letting the framework control it), perhaps you can use one of the built-in explicit animations classes. For more information, watch Making your first directional animations with built-in explicit animations. (Also published as a companion article.)

如果你需要从头开始构建显式动画，请观看通过 AnimatedBuilder 和 AnimatedWidget 创建一个自定义动画。（同时也发布了一篇配套文章。）

If you need to build an explicit animation from scratch, watch Creating custom explicit animations with AnimatedBuilder and AnimatedWidget. (Also published as a companion article.)

想要更深入的理解动画在 Flutter 中的工作方式，请观看深入理解动画。（同时也发布了一篇配套文章。）

For a deeper understanding of just how animations work in Flutter, watch Animation deep dive. (Also published as a companion article.)

Codelabs, 教程和文章

Codelabs, tutorials, and articles

通过下面的资源可以很好的学习 Flutter 动画框架。这些文档循序渐进地讲解如何编写动画代码。

The following resources are a good place to start learning the Flutter animation framework. Each of these documents shows how to write animation code.

隐式动画 codelab
涵盖了如何使用隐式动画的分步说明及交互示例。
Implicit animations codelab
Covers how to use implicit animations using step-by-step instructions and interactive examples.
动画教程
阐释了 Flutter 动画包中的基本类（控制器，动画，曲线，监听器，构建器），这些可以帮助您使用不同的动画 APIs 完成补间动画。
Animations tutorial
Explains the fundamental classes in the Flutter animation package (controllers, Animatable, curves, listeners, builders), as it guides you through a progression of tween animations using different aspects of the animation APIs.
使用 Flutter 从零到一, 第一部分和第二部分
Medium 文章中有介绍如何使用补间动画创建图表动画。
Zero to One with Flutter, part 1 and part 2
Medium articles showing how to create an animated chart using tweening.
撰写你的第一个 Flutter Web 应用
Codelab 演示如何构建一个根据用户填写的内容以动画展示进度的表单。
Write your first Flutter app on the web
Codelab demonstrating how to create a form that uses animation to show the user’s progress as they fill in the fields.
使用 Flutter 构建美观 UIs
Codelab 演示如何构建简单的聊天应用程序。步骤 7 (应用动画化) 展示了一个新消息动画，使其能从输入区域滑动至消息列表。
Building Beautiful UIs with Flutter
Codelab demonstrating how to build a simple chat app. Step 7 (Animate your app) shows how to animate the new message—sliding it from the input area up to the message list.

Animation types

动画分为两类：补间动画和基于物理动画。下面将解释这些术语的含义，并帮助您找到更多相关资源。在一些情况下，我们现有的最佳文档是 Flutter gallery 中的示例代码。

Generally, animations are either tween- or physics-based. The following sections explain what these terms mean, and point you to resources where you can learn more.

补间动画

Tween animation

补间动画是“介于两者之间”的缩写。在补间动画中，定义了起点和终点以及时间轴，再定义过渡时间和速度的曲线。然后框架会计算如何从起点过渡到终点。

Short for in-betweening. In a tween animation, the beginning and ending points are defined, as well as a timeline, and a curve that defines the timing and speed of the transition. The framework calculates how to transition from the beginning point to the end point.

上文列出的文档，比如在 Flutter 应用里实现动画效果并不是特别针对补间动画的，但是其示例中使用了补间动画。

The documents listed above, such as the animations tutorial are not about tweening, specifically, but they use tweens in their examples.

基于物理基础的动画

Physics-based animation

在基于物理基础的动画中，动作是模拟真实世界的行为来进行建模的。举个例子，当您抛球时，球落地的时间和位置取决于抛出的速度和距离地面的高度。类似地，附在弹簧上的球和附在绳子上的球掉落（和反弹）方式是不一样的。

In physics-based animation, motion is modeled to resemble real-world behavior. When you toss a ball, for example, where and when it lands depends on how fast it was tossed and how far it was from the ground. Similarly, dropping a ball attached to a spring falls (and bounces) differently than dropping a ball attached to a string.

使用物理模拟动画效果
在 Flutter cookbook 中的动画教程。
Animate a widget using a physics simulation
A recipe in the animations section of the Flutter cookbook.
Flutter Gallery
在 Material 组件 下，Grid 示例演示了一个抛物动画。从网格中选取一个图像并放大。您可以通过使用投掷和拖动来平移图像。
Flutter Gallery
Under Material Components, the Grid example demonstrates a fling animation. Select one of the images from the grid and zoom in. You can pan the image with flinging or dragging gestures.
请参考 API 文档 AnimationController.animateWith 和 SpringSimulation。
Also see the API documentation for AnimationController.animateWith and SpringSimulation.

预置动画

Pre-canned animations

如果你在使用 Material widgets，你也许想要看看 pub.dev 上的 animations package。这个 package 包含了以下内置常用模式： Container 变换、共享轴变化、渐变穿透和渐变变换。

If you are using Material widgets, you might check out the animations package available on pub.dev. This package contains pre-built animations for the following commonly used patterns: Container transforms, shared axis transitions, fade through transitions, and fade transitions.

常见动画模式

Common animation patterns

大多数 UX 或动效设计师在设计 UI 时都会寻找主要动画模式。本章的列表将介绍一些常见的动画模式，并向你介绍更多学习它们的地方。

Most UX or motion designers find that certain animation patterns are used repeatedly when designing a UI. This section lists some of the commonly used animation patterns, and tells you where to learn more.

列表或网格动画

Animated list or grid

这种模式用于在列表或网格中添加或删除元素。

This pattern involves animating the addition or removal of elements from a list or grid.

AnimatedList example
这个来自 Sample app catalog 的演示展示了如何动态添加元素至列表或删除选定元素。当用户使用 plus (+) 和 minus (-) 按钮修改列表时，会同步到内部 Dart 列表。
AnimatedList example
This demo, from the Sample app catalog, shows how to animate adding an element to a list, or removing a selected element. The internal Dart list is synced as the user modifies the list using the plus (+) and minus (-) buttons.

共享元素转换

Shared element transition

在这个模式中，用户从页面中选择一个元素，通常是图像，然后 UI 会在新页面中为指定元素添加动画，并生成更多细节。在 Flutter 中，您可以通过 Hero widget 轻松实现路径（页面）间的共享元素转换动画。

In this pattern, the user selects an element—often an image—from the page, and the UI animates the selected element to a new page with more detail. In Flutter, you can easily implement shared element transitions between routes (pages) using the Hero widget.

Hero animations 如何创建两种风格的 Hero 动画：
Hero animations How to create two styles of Hero animations:
- 当改变位置和大小时，Hero 从一页飞至另一页。
  The hero flies from one page to another while changing position and size.
- Hero 的边界改变形状由圆变方，同时从一页飞至另一页。
  The hero’s boundary changes shape, from a circle to a square, as its flies from one page to another.
Flutter Gallery
您可以自己自己创建 Gallery 应用程序，或者到 Play 商店中下载。 Shrine 演示中有关于 Hero 动画的示例。
Flutter Gallery
You can build the Gallery app yourself, or download it from the Play Store. The Shrine demo includes an example of a hero animation.
另请参阅 API 文档 Hero、Navigator 和 PageRoute 类。
Also see the API documentation for the Hero, Navigator, and PageRoute classes.

交织动画

Staggered animation

动画被分解成较小的动作，其中一些动作被延迟。这些小动画可以是连续的，也可以部分或完全重叠。

Animations that are broken into smaller motions, where some of the motion is delayed. The smaller animations might be sequential, or might partially or completely overlap.

交织动画
Staggered Animations

其他资源

Other resources

以下链接可以了解更多 Flutter 动画：

Learn more about Flutter animations at the following links:

Animation samples from the Sample app catalog.
Animation recipes from the Flutter cookbook.
Animation videos from the Flutter YouTube channel.
动画概览
动画库中主要类简介，以及 Flutter 动画结构。
Animations: overview
A look at some of the major classes in the animations library, and Flutter’s animation architecture.
动画及动作 Widgets
Flutter APIs 提供的动画 widgets 目录。
Animation and motion widgets
A catalog of some of the animation widgets provided in the Flutter APIs.
The animation library in the Flutter API documentation
The animation API for the Flutter framework. This link takes you to a technical overview page for the library.

动画概览

Animation
- addListener
- addStatusListener
AnimationController
补间动画
Tweens
架构
Architecture

Flutter 中的动画系统基于 Animation。 Widgets 可以直接将这些动画合并到自己的 build 方法中来读取它们的当前值或者监听它们的状态变化，或者可以将其作为的更复杂动画的基础传递给其他 widgets。

The animation system in Flutter is based on typed Animation objects. Widgets can either incorporate these animations in their build functions directly by reading their current value and listening to their state changes or they can use the animations as the basis of more elaborate animations that they pass along to other widgets.

Animation

动画系统的首要组成部分就是 Animation 类。一个动画表现为可在它的生命周期内发生变化的特定类型的值。大多数需要执行动画的 widgets 都需要接收一个 Animation 对象作为参数，从而能从中获取到动画的当前状态值以及应该监听哪些具体值的更改。

The primary building block of the animation system is the Animation class. An animation represents a value of a specific type that can change over the lifetime of the animation. Most widgets that perform an animation receive an Animation object as a parameter, from which they read the current value of the animation and to which they listen for changes to that value.

`addListener`

每当动画的状态值发生变化时，动画都会通知所有通过 addListener 添加的监听器。通常，一个正在监听动画的 State 对象会调用自身的 setState 方法，将自身传入这些监听器的回调函数来通知 widget 系统需要根据新状态值进行重新构建。

Whenever the animation’s value changes, the animation notifies all the listeners added with addListener. Typically, a State object that listens to an animation calls setState on itself in its listener callback to notify the widget system that it needs to rebuild with the new value of the animation.

这种模式非常常见，所以有两个 widgets 可以帮助其他 widgets 在动画改变值时进行重新构建： AnimatedWidget 和 AnimatedBuilder。第一个是 AnimatedWidget，对于无状态动画 widgets 来说是尤其有用的。要使用 AnimatedWidget，只需继承它并实现一个 build 方法。第二个是 AnimatedBuilder，对于希望将动画作为复杂 widgets 的 build 方法的其中一部分的情况非常有用。要使用 AnimatedBuilder，只需构造 widget 并将 AnimatedBuilder 传递给 widget 的 builder 方法。

This pattern is so common that there are two widgets that help widgets rebuild when animations change value: AnimatedWidget and AnimatedBuilder. The first, AnimatedWidget, is most useful for stateless animated widgets. To use AnimatedWidget, simply subclass it and implement the build function. The second, AnimatedBuilder, is useful for more complex widgets that wish to include an animation as part of a larger build function. To use AnimatedBuilder, simply construct the widget and pass it a builder function.

`addStatusListener`

动画还提供了一个 AnimationStatus，表示动画将如何随时间进行变化。每当动画的状态发生变化时，动画都会通知所有通过 addStatusListener 添加的监听器。通常情况下，动画会从 dismissed 状态开始，表示它处于变化区间的开始点。举例来说，从 0.0 到 1.0 的动画在 dismissed 状态时的值应该是 0.0。动画进行的下一状态可能是 forward（比如从 0.0 到 1.0）或者 reverse（比如从 1.0 到 0.0）。最终，如果动画到达其区间的结束点（比如 1.0），则动画会变成 completed 状态。

Animations also provide an AnimationStatus, which indicates how the animation will evolve over time. Whenever the animation’s status changes, the animation notifies all the listeners added with addStatusListener. Typically, animations start out in the dismissed status, which means they’re at the beginning of their range. For example, animations that progress from 0.0 to 1.0 will be dismissed when their value is 0.0. An animation might then run forward (from 0.0 to 1.0) or perhaps in reverse (from 1.0 to 0.0). Eventually, if the animation reaches the end of its range (1.0), the animation reaches the completed status.

AnimationController

要创建动画，首先要创建一个 AnimationController。除了作为动画本身，AnimationController 还可以用来控制动画。例如，你可以通过控制器让动画正向播放 forward 或停止动画 stop。你还可以添加物理模拟效果 fling（例如弹簧效果）来驱动动画。

To create an animation, first create an AnimationController. As well as being an animation itself, an AnimationController lets you control the animation. For example, you can tell the controller to play the animation forward or stop the animation. You can also fling animations, which uses a physical simulation, such as a spring, to drive the animation.

一旦创建了一个动画控制器，你可以基于它来构建其他动画。例如，你可以创建一个 ReverseAnimation，效果是复制一个动画但是将其反向运行（比如从 1.0 到 0.0）。同样，你可以创建一个 CurvedAnimation，效果是用 Curve 来调整动画的值。

Once you’ve created an animation controller, you can start building other animations based on it. For example, you can create a ReverseAnimation that mirrors the original animation but runs in the opposite direction (from 1.0 to 0.0). Similarly, you can create a CurvedAnimation whose value is adjusted by a Curve.

补间动画

Tweens

如果想要在 0.0 到 1.0 的区间之外设置动画，可以使用 Tween<T>，它可以在它的 begin 值和 end 值之间进行插值补间。许多类都有特定的 Tween 子类，它们能提供基于特定类型的插值行为。例如， ColorTween 可以在颜色间进行插值， RectTween 可以在矩形之间进行插值。你可以通过创建自己的 Tween 子类并覆盖其 lerp 方法来定义自己的补间动画。

To animate beyond the 0.0 to 1.0 interval, you can use a Tween<T>, which interpolates between its begin and end values. Many types have specific Tween subclasses that provide type-specific interpolation. For example, ColorTween interpolates between colors and RectTween interpolates between rects. You can define your own interpolations by creating your own subclass of Tween and overriding its lerp function.

补间动画本身只定义了如何在两个值之间进行插值。要获取动画当前帧的具体值，还需要一个动画来确定当前状态。有两种方法可以将补间动画与动画组合在一起以获得动画的具体值：

By itself, a tween just defines how to interpolate between two values. To get a concrete value for the current frame of an animation, you also need an animation to determine the current state. There are two ways to combine a tween with an animation to get a concrete value:

你可以用 evaluate 方法处理动画的当前值从而得到对应的插值。这种方法对于已经监听动画并因此在动画改变值时重新构建的 widgets 是最有效的。
You can evaluate the tween at the current value of an animation. This approach is most useful for widgets that are already listening to the animation and hence rebuilding whenever the animation changes value.
你可以用 animate 方法处理一个动画。相对于返回单个值，animate 方法返回一个包含补间动画插值的新的 Animation。这种方法对于当你想要将新创建的动画提供给另一个 widget 时最有效，它可以直接读取包含补间动画的插值以及监听对应插值的更改。
You can animate the tween based on the animation. Rather than returning a single value, the animate function returns a new Animation that incorporates the tween. This approach is most useful when you want to give the newly created animation to another widget, which can then read the current value that incorporates the tween as well as listen for changes to the value.

架构

Architecture

动画实际上是由许多核心模块共同构建的。

Animations are actually built from a number of core building blocks.

调度器

Scheduler

SchedulerBinding 是一个暴露出 Flutter 调度原语的单例类。

The SchedulerBinding is a singleton class that exposes the Flutter scheduling primitives.

在这一节，关键原语是帧回调。每当一帧需要在屏幕上显示时， Flutter 的引擎会触发一个 “开始帧” 回调，调度程序会将其多路传输给所有使用 scheduleFrameCallback() 注册的监听器。所有这些回调不管在任意状态或任意时刻都可以收到这一帧的绝对时间戳。由于所有回调收到时间戳都相同，因此这些回调触发的任何动画看起来都是完全同步的，即使它们需要几毫秒才能执行。

For this discussion, the key primitive is the frame callbacks. Each time a frame needs to be shown on the screen, Flutter’s engine triggers a “begin frame” callback that the scheduler multiplexes to all the listeners registered using scheduleFrameCallback(). All these callbacks are given the official time stamp of the frame, in the form of a Duration from some arbitrary epoch. Since all the callbacks have the same time, any animations triggered from these callbacks will appear to be exactly synchronised even if they take a few milliseconds to be executed.

运行器

Tickers

Ticker 类挂载在调度器的 scheduleFrameCallback() 的机制上，来达到每次运行都会触发回调的效果。

The Ticker class hooks into the scheduler’s scheduleFrameCallback() mechanism to invoke a callback every tick.

一个 Ticker 可以被启动和停止，启动时，它会返回一个 Future，这个 Future 在 Ticker 停止时会被改为完成状态。

A Ticker can be started and stopped. When started, it returns a Future that will resolve when it is stopped.

每次运行, Ticker 都会为回调函数提供从 Ticker 开始运行到现在的持续时间。

Each tick, the Ticker provides the callback with the duration since the first tick after it was started.

因为运行器总是会提供在自它们开始运行以来的持续时间，所以所有运行器都是同步的。如果你在两帧之间的不同时刻启动三个运行器，它们都会被同步到相同的开始时间，并随后同步运行。

Because tickers always give their elapsed time relative to the first tick after they were started; tickers are all synchronised. If you start three tickers at different times between two ticks, they will all nonetheless be synchronised with the same starting time, and will subsequently tick in lockstep. Like people at a bus-stop, all the tickers wait for a regularly occurring event (the tick) to begin moving (counting time).

模拟器

Simulations

Simulation 抽象类将相对时间值（运行时间）映射为双精度值，并且有完成的概念。

The Simulation abstract class maps a relative time value (an elapsed time) to a double value, and has a notion of completion.

原则上，模拟器是无状态的，但在实践中，一些模拟器（例如 BouncingScrollSimulation 和 ClampingScrollSimulation）在查询时会不可逆地被改变状态。

In principle simulations are stateless but in practice some simulations (for example, BouncingScrollSimulation and ClampingScrollSimulation) change state irreversibly when queried.

针对不同的效果，Simulation 类有各种具体实现。

There are various concrete implementations of the Simulation class for different effects.

Animatables

Animatable 抽象类将双精度值映射为特定类型的值。

The Animatable abstract class maps a double to a value of a particular type.

Animatable 类是无状态和不可变的。

Animatable classes are stateless and immutable.

补间动画

Tweens

Tween<T> 抽象类将名义范围为 0.0-1.0 的双精度值映射到某个类型值（例如 Color 或其他双精度值)。它属于 Animatable。

The Tween<T> abstract class maps a double value nominally in the range 0.0-1.0 to a typed value (for example, a Color, or another double). It is an Animatable.

它有一个输出类型（T）的概念，这个输出类型有一个 begin 值和一个end 值，以及在给定输入值的起始值和结束值（名义范围为 0.0-1.0 的双精度值）之间插值（lerp）的方法。

It has a notion of an output type (T), a begin value and an end value of that type, and a way to interpolate (lerp) between the begin and end values for a given input value (the double nominally in the range 0.0-1.0).

Tween 类是无状态和不可变的。

Tween classes are stateless and immutable.

组合 animatables

Composing animatables

将 Animatable<double>（父类）传递给一个 Animatable 的 chain() 方法会创建一个新的 Animatable 子类，这个子类会先应用父类的映射，然后应用子类的映射。

Passing an Animatable<double> (the parent) to an Animatable’s chain() method creates a new Animatable subclass that applies the parent’s mapping then the child’s mapping.

曲线

Curves

Curve 抽象类将名义范围为 0.0-1.0 的双精度值映射到名义范围为 0.0-1.0 的双精度值。

The Curve abstract class maps doubles nominally in the range 0.0-1.0 to doubles nominally in the range 0.0-1.0.

Curve 类是无状态和不可变的。

Curve classes are stateless and immutable.

动画

Animations

Animation 抽象类提供给定类型的值、动画方向的概念和动画状态和一个监听器接口，这个监听器接口用来注册值或状态的改变时被调用的回调。

The Animation abstract class provides a value of a given type, a concept of animation direction and animation status, and a listener interface to register callbacks that get invoked when the value or status change.

有些 Animation 的子类值是永远不变的（kAlwaysCompleteAnimation、kAlwaysDismissedAnimation 和 AlwaysStoppedAnimation），在这些子类上注册回调没有任何效果，因为这些回调永远不会被调用。

Some subclasses of Animation have values that never change (kAlwaysCompleteAnimation, kAlwaysDismissedAnimation, AlwaysStoppedAnimation); registering callbacks on these has no effect as the callbacks are never called.

Animation<double> 变量很特殊，因为它可以被用来表示名义范围为 0.0-1.0 的双精度值，也就是 Curve 和 Tween 类以及动画的一些其他子类所期望的输入。

The Animation<double> variant is special because it can be used to represent a double nominally in the range 0.0-1.0, which is the input expected by Curve and Tween classes, as well as some further subclasses of Animation.

有些 Animation 的子类是无状态的，只是将监听器转发给其父级；另外有些是有状态的。

Some Animation subclasses are stateless, merely forwarding listeners to their parents. Some are very stateful.

组合动画

Composable animations

大多数 Animation 子类都采用明确的 “父级提供的” Animation<double>。可以说它们是由父级驱动的。

Most Animation subclasses take an explicit “parent” Animation<double>. They are driven by that parent.

CurvedAnimation 子类接收一个 Animation<double> 类（父级）和几个 Curve 类（正向和反向曲线）作为输入，并使用父级的值作为输入提供给曲线来确定它的输出。 CurvedAnimation 是不可变和无状态的。

The CurvedAnimation subclass takes an Animation<double> class (the parent) and a couple of Curve classes (the forward and reverse curves) as input, and uses the value of the parent as input to the curves to determine its output. CurvedAnimation is immutable and stateless.

ReverseAnimation 子类接收一个 Animation<double> 类作为它的父级，但反转动画所有的值。它假定父级使用名义范围为 0.0-1.0 的双精度值，并返回范围为 1.0-0.0 的值。父级动画的状态和方向也会被反转。 ReverseAnimation 是不可变和无状态的。

The ReverseAnimation subclass takes an Animation<double> class as its parent and reverses all the values of the animation. It assumes the parent is using a value nominally in the range 0.0-1.0 and returns a value in the range 1.0-0.0. The status and direction of the parent animation are also reversed. ReverseAnimation is immutable and stateless.

ProxyAnimation 子类接收一个 Animation<double> 类作为其父级，并仅转发该父级的当前状态。然而，父级是可变的。

The ProxyAnimation subclass takes an Animation<double> class as its parent and merely forwards the current state of that parent. However, the parent is mutable.

TrainHoppingAnimation 子类接收两个父类，并在它们的值交叉时在它们之间切换。

The TrainHoppingAnimation subclass takes two parents, and switches between them when their values cross.

动画控制器

Animation Controllers

AnimationController 是一个有状态的 Animation<double>，并使用一个 Ticker 来提供生命周期，它可以被启动和停止。每次运行，它会收集从启动开始经过的时间，并将其传递给 Simulation 来获得一个值，这就是在当前时间戳下它应该传递的值。如果 Simulation 反馈此时动画已经结束了，则控制器就会自行停止。

The AnimationController is a stateful Animation<double> that uses a Ticker to give itself life. It can be started and stopped. At each tick, it takes the time elapsed since it was started and passes it to a Simulation to obtain a value. That is then the value it reports. If the Simulation reports that at that time it has ended, then the controller stops itself.

可以给动画控制器设置动画运行的下限和上限，还有动画的持续时间。

The animation controller can be given a lower and upper bound to animate between, and a duration.

在一般情况下（使用 forward()、reverse()、play() 或者 resume()），动画控制器只是简单地在持续时间内线性地从下限至上限（反之亦然，用于在反向方向）进行插值补间。

In the simple case (using forward() or reverse()), the animation controller simply does a linear interpolation from the lower bound to the upper bound (or vice versa, for the reverse direction) over the given duration.

当使用 repeat() 时，动画控制器会在持续时间内线性地在上下边界之间进行插值补间，但会一直重复，不会停止。

When using repeat(), the animation controller uses a linear interpolation between the given bounds over the given duration, but does not stop.

当使用 animateTo() 时，动画控制器会在持续时间内线性地从当前值到给定目标值进行插值补间。如果方法没有指定持续时间，则使用控制器的默认持续时间和控制器的上下限范围来确定动画的速度。

When using animateTo(), the animation controller does a linear interpolation over the given duration from the current value to the given target. If no duration is given to the method, the default duration of the controller and the range described by the controller’s lower bound and upper bound is used to determine the velocity of the animation.

当使用 fling() 时，一个 Force 被用来创建一个特定的模拟器，然后用来驱动控制器。

When using fling(), a Force is used to create a specific simulation which is then used to drive the controller.

当使用 animateWith() 时，给定的模拟器会被用于驱动控制器。

When using animateWith(), the given simulation is used to drive the controller.

这些方法都会返回 Ticker 提供的将来值，交由控制器下一次停止或改变模拟器时来完成。

These methods all return the future that the Ticker provides and which will resolve when the controller next stops or changes simulation.

将 animatables 附加到动画上

Attaching animatables to animations

将 Animation<double>（新父级）传递给一个 Animatable 类的 animate() 方法将创建一个新的 Animation 子类，它的作用类似于 Animatable，但是由给定的父级驱动。

Passing an Animation<double> (the new parent) to an Animatable’s animate() method creates a new Animation subclass that acts like the Animatable but is driven from the given parent.

教程 | 在 Flutter 应用里实现动画效果

基本动画概念和类
Essential animation concepts and classes
动画示例
Animation examples
下面的步骤
Next steps

本教程将讲解如何在 Flutter 中构建显式动画。我们先来介绍一些动画库中的基本概念，类和方法，然后列举五个动画示例。这些示例互相关联，展示了动画库的不同方面。

This tutorial shows you how to build explicit animations in Flutter. After introducing some of the essential concepts, classes, and methods in the animation library, it walks you through 5 animation examples. The examples build on each other, introducing you to different aspects of the animation library.

Flutter SDK 也内置了显式动画，比如 FadeTransition，SizeTransition 和 SlideTransition。这些简单的动画可以通过设置起点和终点来触发。它们比下面介绍的显式动画更容易实现。

The Flutter SDK also provides built-in explicit animations, such as FadeTransition, SizeTransition, and SlideTransition. These simple animations are triggered by setting a beginning and ending point. They are simpler to implement than custom explicit animations, which are described here.

基本动画概念和类

Essential animation concepts and classes

重点是什么？

What's the point?

Animation，Flutter 动画库中的核心类，插入用于指导动画的值。
Animation, a core class in Flutter’s animation library, interpolates the values used to guide an animation.
Animation 对象知道动画目前的状态（例如，是否开始，暂停，前进或倒退），但是对屏幕上显示的内容一无所知。
An Animation object knows the current state of an animation (for example, whether it’s started, stopped, or moving forward or in reverse), but doesn’t know anything about what appears onscreen.
AnimationController 管理 Animation。
An AnimationController manages the Animation.
CurvedAnimation 定义进程为非线性曲线。
A CurvedAnimation defines progression as a non-linear curve.
Tween 为动画对象插入一个范围值。例如，Tween 可以定义插入值由红到蓝，或从 0 到 255。
A Tween interpolates between the range of data as used by the object being animated. For example, a Tween might define an interpolation from red to blue, or from 0 to 255.
使用 Listeners 和 StatusListeners 监视动画状态变化。
Use Listeners and StatusListeners to monitor animation state changes.

Flutter 中的动画系统基于类型化的 Animation 对象。 Widgets 既可以通过读取当前值和监听状态变化直接合并动画到 build 函数，也可以作为传递给其他 widgets 的更精细动画的基础。

Animation<double>

在 Flutter 中，动画对象无法获取屏幕上显示的内容。 Animation 是一个已知当前值和状态（已完成或已解除）的抽象类。一个比较常见的动画类型是 Animation<double>。

In Flutter, an Animation object knows nothing about what is onscreen. An Animation is an abstract class that understands its current value and its state (completed or dismissed). One of the more commonly used animation types is Animation<double>.

一个 Animation 对象在一段时间内，持续生成介于两个值之间的插入值。这个 Animation 对象输出的可能是直线，曲线，阶梯函数，或者任何自定义的映射。根据 Animation 对象的不同控制方式，它可以反向运行，或者中途切换方向。

An Animation object sequentially generates interpolated numbers between two values over a certain duration. The output of an Animation object might be linear, a curve, a step function, or any other mapping you can devise. Depending on how the Animation object is controlled, it could run in reverse, or even switch directions in the middle.

动画还可以插入除 double 以外的类型，比如 Animation<Color> 或者 Animation<Size>。

Animations can also interpolate types other than double, such as Animation<Color> or Animation<Size>.

Animation 对象具有状态。它的当前值在 .value 中始终可用。

An Animation object has state. Its current value is always available in the .value member.

Animation 对象与渲染或 build() 函数无关。

An Animation object knows nothing about rendering or build() functions.

CurvedAnimation

CurvedAnimation 定义动画进程为非线性曲线。

A CurvedAnimation defines the animation’s progress as a non-linear curve.

animation = CurvedAnimation(parent: controller, curve: Curves.easeIn);

提示

Curves 类定义了很多常用曲线，或者您也可以自定义。例如：

The Curves class defines many commonly used curves, or you can create your own. For example:

import 'dart:math';

class ShakeCurve extends Curve {
  @override
  double transform(double t) => sin(t * pi * 2);
}

浏览 Curves 文档以获取完整的（带有预览）Flutter 附带的 Curves 常数列表。

Browse the Curves documentation for a complete listing (with visual previews) of the Curves constants that ship with Flutter.

CurvedAnimation 和 AnimationController（下面将会详细说明）都是 Animation<double> 类型，所以可以互换使用。 CurvedAnimation 封装正在修改的对象 — 不需要将 AnimationController 分解成子类来实现曲线。

CurvedAnimation and AnimationController (described in the next section) are both of type Animation<double>, so you can pass them interchangeably. The CurvedAnimation wraps the object it’s modifying—you don’t subclass AnimationController to implement a curve.

AnimationController

AnimationController 是个特殊的 Animation 对象，每当硬件准备新帧时，他都会生成一个新值。默认情况下，AnimationController 在给定期间内会线性生成从 0.0 到 1.0 的数字。例如，这段代码创建了一个动画对象，但是没有启动运行。

AnimationController is a special Animation object that generates a new value whenever the hardware is ready for a new frame. By default, an AnimationController linearly produces the numbers from 0.0 to 1.0 during a given duration. For example, this code creates an Animation object, but does not start it running:

controller =
    AnimationController(duration: const Duration(seconds: 2), vsync: this);

AnimationController 源自于 Animation<double>，所以可以用在任何需要 Animation 对象的地方。但是 AnimationController 还有其他方法控制动画。例如，使用 .forward() 方法启动动画。数字的生成与屏幕刷新关联，所以一般来说每秒钟会生成 60 个数字。数字生成之后，每个动画对象都调用附加 Listener 对象。为每个 child 创建自定义显示列表，请参考 RepaintBoundary。

AnimationController derives from Animation<double>, so it can be used wherever an Animation object is needed. However, the AnimationController has additional methods to control the animation. For example, you start an animation with the .forward() method. The generation of numbers is tied to the screen refresh, so typically 60 numbers are generated per second. After each number is generated, each Animation object calls the attached Listener objects. To create a custom display list for each child, see RepaintBoundary.

创建 AnimationController 的同时，也赋予了一个 vsync 参数。 vsync 的存在防止后台动画消耗不必要的资源。您可以通过添加 SingleTickerProviderStateMixin 到类定义，将有状态的对象用作 vsync。可参考 GitHub 网站 animate1 中的示例。

When creating an AnimationController, you pass it a vsync argument. The presence of vsync prevents offscreen animations from consuming unnecessary resources. You can use your stateful object as the vsync by adding SingleTickerProviderStateMixin to the class definition. You can see an example of this in animate1 on GitHub.

提示

在一些情况下，一个位置可能会超过 AnimationController 的 0.0-1.0 的范围。例如，fling() 函数允许提供速度，力和位置（通过 Force 对象）。这个位置可以是任意的，所以可能会超出 0.0-1.0 的范围。

In some cases, a position might exceed the AnimationController’s 0.0-1.0 range. For example, the fling() function allows you to provide velocity, force, and position (via the Force object). The position can be anything and so can be outside of the 0.0 to 1.0 range.

即使 AnimationController 在范围内， CurvedAnimation 也可能会出现超出 0.0-1.0 范围的情况。根据所选曲线的不同，CurvedAnimation 的输出范围可能会超过输入。举个例子，弹性曲线（比如Curves.elasticIn）会明显超出或低于默认范围。

A CurvedAnimation can also exceed the 0.0 to 1.0 range, even if the AnimationController doesn’t. Depending on the curve selected, the output of the CurvedAnimation can have a wider range than the input. For example, elastic curves such as Curves.elasticIn significantly overshoots or undershoots the default range.

Tween

在默认情况下，AnimationController 对象的范围是 0.0-0.1。如果需要不同的范围或者不同的数据类型，可以使用 Tween 配置动画来插入不同的范围或数据类型。例如下面的示例中，Tween 的范围是 -200 到 0.0。

By default, the AnimationController object ranges from 0.0 to 1.0. If you need a different range or a different data type, you can use a Tween to configure an animation to interpolate to a different range or data type. For example, the following Tween goes from -200.0 to 0.0:

tween = Tween<double>(begin: -200, end: 0);

Tween 是无状态的对象，只有 begin 和 end。 Tween 的这种单一用途用来定义从输入范围到输出范围的映射。输入范围一般为 0.0-1.0，但这并不是必须的。

A Tween is a stateless object that takes only begin and end. The sole job of a Tween is to define a mapping from an input range to an output range. The input range is commonly 0.0 to 1.0, but that’s not a requirement.

Tween 源自 Animatable<T>，而不是 Animation<T>。像动画这样的可动画元素不必重复输出。例如，ColorTween 指定了两种颜色之间的过程。

A Tween inherits from Animatable<T>, not from Animation<T>. An Animatable, like Animation, doesn’t have to output double. For example, ColorTween specifies a progression between two colors.

colorTween = ColorTween(begin: Colors.transparent, end: Colors.black54);

Tween 对象不存储任何状态。而是提供 evaluate(Animation<double> animation) 方法，将映射函数应用于动画当前值。 Animation 对象的当前值可以在 .value 方法中找到。 evaluate 函数还执行一些内部处理内容，比如确保当动画值在 0.0 和1.0 时分别返回起始点和终点。

A Tween object does not store any state. Instead, it provides the evaluate(Animation<double> animation) method that applies the mapping function to the current value of the animation. The current value of the Animation object can be found in the .value method. The evaluate function also performs some housekeeping, such as ensuring that begin and end are returned when the animation values are 0.0 and 1.0, respectively.

Tween.animate

要使用 Tween 对象，请在 Tween 调用 animate()，传入控制器对象。例如，下面的代码在 500 ms 的进程中生成 0-255 范围内的整数值。

To use a Tween object, call animate() on the Tween, passing in the controller object. For example, the following code generates the integer values from 0 to 255 over the course of 500 ms.

AnimationController controller = AnimationController(
    duration: const Duration(milliseconds: 500), vsync: this);
Animation<int> alpha = IntTween(begin: 0, end: 255).animate(controller);

下面的示例展示了一个控制器，一个曲线，和一个 Tween。

The following example shows a controller, a curve, and a Tween:

AnimationController controller = AnimationController(
    duration: const Duration(milliseconds: 500), vsync: this);
final Animation<double> curve =
    CurvedAnimation(parent: controller, curve: Curves.easeOut);
Animation<int> alpha = IntTween(begin: 0, end: 255).animate(curve);

动画通知

Animation notifications

一个 Animation 对象可以有不止一个 Listener 和 StatusListener，用 addListener() 和 addStatusListener() 来定义。当动画值改变时调用 Listener。 Listener 最常用的操作是调用 setState() 进行重建。当一个动画开始，结束，前进或后退时，会调用 StatusListener，用 AnimationStatus 来定义。下一部分有关于 addListener() 方法的示例，在监控动画过程中也有 addStatusListener() 的示例。

An Animation object can have Listeners and StatusListeners, defined with addListener() and addStatusListener(). A Listener is called whenever the value of the animation changes. The most common behavior of a Listener is to call setState() to cause a rebuild. A StatusListener is called when an animation begins, ends, moves forward, or moves reverse, as defined by AnimationStatus. The next section has an example of the addListener() method, and Monitoring the progress of the animation shows an example of addStatusListener().

动画示例

Animation examples

这部分列举了五个动画示例，每个示例都提供了源代码的链接。

This section walks you through 5 animation examples. Each section provides a link to the source code for that example.

渲染动画

Rendering animations

要点

What's the point?

如何使用 addListener() 和 setState() 为 widget 添加基础动画。
How to add basic animation to a widget using addListener() and setState().
每次动画生成一个新的数字，addListener() 函数就会调用 setState()。
Every time the Animation generates a new number, the addListener() function calls setState().
如何使用所需的 vsync 参数定义一个 AnimationController。
How to define an AnimationController with the required vsync parameter.
理解 “..addListener” 中的 “..” 语法，也称为 Dart 的 cascade notation。
Understanding the “..” syntax in “..addListener”, also known as Dart’s cascade notation.
如需使类私有，在名字前面添加下划线（_）。
To make a class private, start its name with an underscore (_).

目前为止，我们学习了如何随着时间生成数字序列。但屏幕上并未显示任何内容。要显示一个 Animation 对象，需将 Animation 对象存储为您的 widget 成员，然后用它的值来决定如何绘制。

So far you’ve learned how to generate a sequence of numbers over time. Nothing has been rendered to the screen. To render with an Animation object, store the Animation object as a member of your widget, then use its value to decide how to draw.

参考下面的应用程序，它没有使用动画绘制 Flutter logo。

Consider the following app that draws the Flutter logo without animation:

import 'package:flutter/material.dart';

void main() => runApp(const LogoApp());

class LogoApp extends StatefulWidget {
  const LogoApp({Key? key}) : super(key: key);

  @override
  _LogoAppState createState() => _LogoAppState();
}

class _LogoAppState extends State<LogoApp> {
  @override
  Widget build(BuildContext context) {
    return Center(
      child: Container(
        margin: const EdgeInsets.symmetric(vertical: 10),
        height: 300,
        width: 300,
        child: const FlutterLogo(),
      ),
    );
  }
}

源代码: animate0

App source: animate0

下面的代码是加入动画效果的，logo 从无到全屏。当定义 AnimationController 时，必须要使用一个 vsync 对象。在 AnimationController 部分会具体介绍 vsync 参数。

The following shows the same code modified to animate the logo to grow from nothing to full size. When defining an AnimationController, you must pass in a vsync object. The vsync parameter is described in the AnimationController section.

对比无动画示例，改动部分被突出显示：

The changes from the non-animated example are highlighted:

{animate0 → animate1}/lib/main.dart Viewed

@@ -9,16 +9,39 @@
   _LogoAppState createState() => _LogoAppState();
 }
-class _LogoAppState extends State<LogoApp> {
+class _LogoAppState extends State<LogoApp> with SingleTickerProviderStateMixin {
+  late Animation<double> animation;
+  late AnimationController controller;
+  @override
+  void initState() {
+    super.initState();
+    controller =
+        AnimationController(duration: const Duration(seconds: 2), vsync: this);
+    animation = Tween<double>(begin: 0, end: 300).animate(controller)
+      ..addListener(() {
+        setState(() {
+          // The state that has changed here is the animation object’s value.
+        });
+      });
+    controller.forward();
+  }
   @override
   Widget build(BuildContext context) {
     return Center(
       child: Container(
         margin: const EdgeInsets.symmetric(vertical: 10),
-        height: 300,
-        width: 300,
+        height: animation.value,
+        width: animation.value,
         child: const FlutterLogo(),
       ),
     );
   }
+  @override
+  void dispose() {
+    controller.dispose();
+    super.dispose();
+  }
 }

源代码: animate1

App source: animate1

因为addListener() 函数调用 setState()，所以每次 Animation 生成一个新的数字，当前帧就被标记为 dirty，使得 build() 再次被调用。在 build() 函数中，container 会改变大小，因为它的高和宽都读取 animation.value，而不是固定编码值。当 State 对象销毁时要清除控制器以防止内存溢出。

The addListener() function calls setState(), so every time the Animation generates a new number, the current frame is marked dirty, which forces build() to be called again. In build(), the container changes size because its height and width now use animation.value instead of a hardcoded value. Dispose of the controller when the State object is discarded to prevent memory leaks.

经过这些小改动，你成功创建了第一个 Flutter 动画。

With these few changes, you’ve created your first animation in Flutter!

Dart 语言技巧： 你可能对于 Dart 的级联操作符（..addListener() 中的两点）不太熟悉。这个语法意思是使用 animate() 的返回值调用 addListener() 方法。参考下面示例：

Dart language tricks: You might not be familiar with Dart’s cascade notation—the two dots in ..addListener(). This syntax means that the addListener() method is called with the return value from animate(). Consider the following example:

animation = Tween<double>(begin: 0, end: 300).animate(controller)
  ..addListener(() {
    // ···
  });

这段代码相当于：

This code is equivalent to:

animation = Tween<double>(begin: 0, end: 300).animate(controller);
animation.addListener(() {
    // ···
  });

更多关于级联操作符的内容，请参考 Dart Language Tour。

You can learn more about cascade notation in the Dart Language Tour.

使用 AnimatedWidget 进行简化

Simplifying with AnimatedWidget

要点

What's the point?

如何使用 AnimatedWidget 帮助类（代替 addListener() 和 setState()）创建动画 widget。
How to use the AnimatedWidget helper class (instead of addListener() and setState()) to create a widget that animates.
利用 AnimatedWidget 创建一个可以运行重复使用动画的 widget。如需区分 widget 过渡，可以使用 AnimatedBuilder，你可以在使用 AnimatedBuilder 进行重构部分查阅更多信息。
Use AnimatedWidget to create a widget that performs a reusable animation. To separate the transition from the widget, use an AnimatedBuilder, as shown in the Refactoring with AnimatedBuilder section.
Flutter API 中的 AnimatedWidget：AnimatedBuilder, RotationTransition, ScaleTransition, SizeTransition, SlideTransition。
Examples of AnimatedWidgets in the Flutter API: AnimatedBuilder, AnimatedModalBarrier, DecoratedBoxTransition, FadeTransition, PositionedTransition, RelativePositionedTransition, RotationTransition, ScaleTransition, SizeTransition, SlideTransition.

AnimatedWidget 基本类可以从动画代码中区分出核心 widget 代码。 AnimatedWidget 不需要保持 State 对象来 hold 动画。可以添加下面的 AnimatedLogo 类：

The AnimatedWidget base class allows you to separate out the core widget code from the animation code. AnimatedWidget doesn’t need to maintain a State object to hold the animation. Add the following AnimatedLogo class:

class AnimatedLogo extends AnimatedWidget {
  const AnimatedLogo({Key? key, required Animation<double> animation})
      : super(key: key, listenable: animation);

  @override
  Widget build(BuildContext context) {
    final animation = listenable as Animation<double>;
    return Center(
      child: Container(
        margin: const EdgeInsets.symmetric(vertical: 10),
        height: animation.value,
        width: animation.value,
        child: const FlutterLogo(),
      ),
    );
  }
}

在绘制时，AnimatedLogo 会读取 animation 当前值。

AnimatedLogo uses the current value of the animation when drawing itself.

LogoApp 持续控制 AnimationController 和 Tween，并将 Animation 对象传给 AnimatedLogo：

The LogoApp still manages the AnimationController and the Tween, and it passes the Animation object to AnimatedLogo:

{animate1 → animate2}/lib/main.dart Viewed

@@ -1,10 +1,28 @@
 import 'package:flutter/material.dart';
 void main() => runApp(const LogoApp());
+class AnimatedLogo extends AnimatedWidget {
+  const AnimatedLogo({Key? key, required Animation<double> animation})
+      : super(key: key, listenable: animation);
+  @override
+  Widget build(BuildContext context) {
+    final animation = listenable as Animation<double>;
+    return Center(
+      child: Container(
+        margin: const EdgeInsets.symmetric(vertical: 10),
+        height: animation.value,
+        width: animation.value,
+        child: const FlutterLogo(),
+      ),
+    );
+  }
+}
 class LogoApp extends StatefulWidget {
   const LogoApp({Key? key}) : super(key: key);
   @override
   _LogoAppState createState() => _LogoAppState();
 }
@@ -15,32 +33,18 @@
   @override
   void initState() {
     super.initState();
     controller =
         AnimationController(duration: const Duration(seconds: 2), vsync: this);
-    animation = Tween<double>(begin: 0, end: 300).animate(controller)
-      ..addListener(() {
-        setState(() {
-          // The state that has changed here is the animation object’s value.
-        });
-      });
+    animation = Tween<double>(begin: 0, end: 300).animate(controller);
     controller.forward();
   }
   @override
-  Widget build(BuildContext context) {
-    return Center(
-      child: Container(
-        margin: const EdgeInsets.symmetric(vertical: 10),
-        height: animation.value,
-        width: animation.value,
-        child: const FlutterLogo(),
-      ),
-    );
-  }
+  Widget build(BuildContext context) => AnimatedLogo(animation: animation);
   @override
   void dispose() {
     controller.dispose();
     super.dispose();
   }

源代码： animate2

App source: animate2

监控动画过程

Monitoring the progress of the animation

了解动画何时改变状态通常是很有用的，比如完成，前进或后退。可以通过 addStatusListener() 来获得提示。下面是之前示例修改后的代码，这样就可以监听状态的改变和更新。修改部分会突出显示：

It’s often helpful to know when an animation changes state, such as finishing, moving forward, or reversing. You can get notifications for this with addStatusListener(). The following code modifies the previous example so that it listens for a state change and prints an update. The highlighted line shows the change:

class _LogoAppState extends State<LogoApp> with SingleTickerProviderStateMixin {
  late Animation<double> animation;
  late AnimationController controller;

  @override
  void initState() {
    super.initState();
    controller =
        AnimationController(duration: const Duration(seconds: 2), vsync: this);
    animation = Tween<double>(begin: 0, end: 300).animate(controller)
      ..addStatusListener((state) => print('$state'));
    controller.forward();
  }
  // ...
}

运行这段代码，得到如下结果：

Running this code produces this output:

AnimationStatus.forward
AnimationStatus.completed

下一步，在起始或结束时，使用 addStatusListener() 反转动画。制造“呼吸”效果：

Next, use addStatusListener() to reverse the animation at the beginning or the end. This creates a “breathing” effect:

{animate2 → animate3}/lib/main.dart Viewed

@@ -35,7 +35,15 @@
   void initState() {
     super.initState();
     controller =
         AnimationController(duration: const Duration(seconds: 2), vsync: this);
-    animation = Tween<double>(begin: 0, end: 300).animate(controller);
+    animation = Tween<double>(begin: 0, end: 300).animate(controller)
+      ..addStatusListener((status) {
+        if (status == AnimationStatus.completed) {
+          controller.reverse();
+        } else if (status == AnimationStatus.dismissed) {
+          controller.forward();
+        }
+      })
+      ..addStatusListener((state) => print('$state'));
     controller.forward();
   }

源代码： animate3

App source: animate3

使用 AnimatedBuilder 进行重构

Refactoring with AnimatedBuilder

要点

What's the point?

AnimatedBuilder 知道如何渲染过渡效果
An AnimatedBuilder understands how to render the transition.
但 AnimatedBuilder 不会渲染 widget，也不会控制动画对象。
An AnimatedBuilder doesn’t know how to render the widget, nor does it manage the Animation object.
使用 AnimatedBuilder 描述一个动画是其他 widget 构建方法的一部分。如果只是单纯需要用可重复使用的动画定义一个 widget，可参考文档：简单使用 AnimatedWidget。
Use AnimatedBuilder to describe an animation as part of a build method for another widget. If you simply want to define a widget with a reusable animation, use an AnimatedWidget, as shown in the Simplifying with AnimatedWidget section.
Flutter API 中 AnimatedBuilders：BottomSheet, ExpansionTile, PopupMenu, ProgressIndicator, RefreshIndicator, Scaffold, SnackBar, TabBar, TextField。
Examples of AnimatedBuilders in the Flutter API: BottomSheet, ExpansionTile, PopupMenu, ProgressIndicator, RefreshIndicator, Scaffold, SnackBar, TabBar, TextField.

animate3 示例代码中有个问题，就是改变动画需要改变渲染 logo 的widget。较好的解决办法是，将任务区分到不同类里：

One problem with the code in the animate3 example, is that changing the animation required changing the widget that renders the logo. A better solution is to separate responsibilities into different classes:

渲染 logo
Render the logo
定义动画对象
Define the Animation object
渲染过渡效果
Render the transition

您可以使用 AnimatedBuilder 类方法来完成分配。 AnimatedBuilder 作为渲染树的一个单独类。像 AnimatedWidget，AnimatedBuilder 自动监听动画对象提示，并在必要时在 widget 树中标出，所以这时不需要调用 addListener()。

You can accomplish this separation with the help of the AnimatedBuilder class. An AnimatedBuilder is a separate class in the render tree. Like AnimatedWidget, AnimatedBuilder automatically listens to notifications from the Animation object, and marks the widget tree dirty as necessary, so you don’t need to call addListener().

应用于 animate4 示例的 widget 树长这样：

The widget tree for the animate4 example looks like this:

AnimatedBuilder widget tree

从 widget 树底部开始，渲染 logo 的代码很容易：

Starting from the bottom of the widget tree, the code for rendering the logo is straightforward:

class LogoWidget extends StatelessWidget {
  const LogoWidget({Key? key}) : super(key: key);

  // Leave out the height and width so it fills the animating parent
  @override
  Widget build(BuildContext context) {
    return Container(
      margin: const EdgeInsets.symmetric(vertical: 10),
      child: const FlutterLogo(),
    );
  }
}

图表中间的三部分都是用 GrowTransition 中的 build() 方法创建的，如下。 GrowTransition widget 本身是无状态的，而且拥有定义过渡动画所需的一系列最终变量。 build() 函数创建并返回 AnimatedBuilder， AnimatedBuilder 使用（Anonymous builder）方法并将 LogoWidget 对象作为参数。渲染过渡效果实际上是在（Anonymous builder）方法中完成的，该方法创建一个适当大小 Container 强制 LogoWidget 配合。

The middle three blocks in the diagram are all created in the build() method in GrowTransition, shown below. The GrowTransition widget itself is stateless and holds the set of final variables necessary to define the transition animation. The build() function creates and returns the AnimatedBuilder, which takes the (Anonymous builder) method and the LogoWidget object as parameters. The work of rendering the transition actually happens in the (Anonymous builder) method, which creates a Container of the appropriate size to force the LogoWidget to shrink to fit.

在下面这段代码中，一个比较棘手的问题是 child 看起来被指定了两次。其实是 child 的外部参照被传递给了 AnimatedBuilder，再传递给匿名闭包，然后用作 child 的对象。最终结果就是 AnimatedBuilder 被插入渲染树的两个 widgets 中间。

One tricky point in the code below is that the child looks like it’s specified twice. What’s happening is that the outer reference of child is passed to AnimatedBuilder, which passes it to the anonymous closure, which then uses that object as its child. The net result is that the AnimatedBuilder is inserted in between the two widgets in the render tree.

class GrowTransition extends StatelessWidget {
  const GrowTransition({required this.child, required this.animation, Key? key})
      : super(key: key);

  final Widget child;
  final Animation<double> animation;

  @override
  Widget build(BuildContext context) {
    return Center(
      child: AnimatedBuilder(
        animation: animation,
        builder: (context, child) {
          return SizedBox(
            height: animation.value,
            width: animation.value,
            child: child,
          );
        },
        child: child,
      ),
    );
  }
}

最后，初始动画的代码看起来很像 animate2 的示例。 initState() 方法创建了 AnimationController 和 Tween，然后用 animate() 绑定它们。神奇的是 build() 方法，它返回一个以LogoWidget 为 child 的 GrowTransition 对象，和一个驱动过渡的动画对象。上面列出了三个主要因素。

Finally, the code to initialize the animation looks very similar to the animate2 example. The initState() method creates an AnimationController and a Tween, then binds them with animate(). The magic happens in the build() method, which returns a GrowTransition object with a LogoWidget as a child, and an animation object to drive the transition. These are the three elements listed in the bullet points above.

{animate2 → animate4}/lib/main.dart Viewed

@@ -1,27 +1,47 @@
 import 'package:flutter/material.dart';
 void main() => runApp(const LogoApp());
-class AnimatedLogo extends AnimatedWidget {
-  const AnimatedLogo({Key? key, required Animation<double> animation})
-      : super(key: key, listenable: animation);
+class LogoWidget extends StatelessWidget {
+  const LogoWidget({Key? key}) : super(key: key);
+  // Leave out the height and width so it fills the animating parent
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      margin: const EdgeInsets.symmetric(vertical: 10),
+      child: const FlutterLogo(),
+    );
+  }
+}
+class GrowTransition extends StatelessWidget {
+  const GrowTransition({required this.child, required this.animation, Key? key})
+      : super(key: key);
+  final Widget child;
+  final Animation<double> animation;
   @override
   Widget build(BuildContext context) {
-    final animation = listenable as Animation<double>;
     return Center(
-      child: Container(
- margin: const EdgeInsets.symmetric(vertical: 10),
- height: animation.value,
-        width: animation.value,
-        child: const FlutterLogo(),
+      child: AnimatedBuilder(
+ animation: animation,
+ builder: (context, child) {
+          return SizedBox(
+            height: animation.value,
+            width: animation.value,
+            child: child,
+          );
+        },
+        child: child,
       ),
     );
   }
 }
 class LogoApp extends StatefulWidget {
   const LogoApp({Key? key}) : super(key: key);
   @override
   _LogoAppState createState() => _LogoAppState();
@@ -34,18 +54,23 @@
   @override
   void initState() {
     super.initState();
     controller =
         AnimationController(duration: const Duration(seconds: 2), vsync: this);
     animation = Tween<double>(begin: 0, end: 300).animate(controller);
     controller.forward();
   }
   @override
-  Widget build(BuildContext context) => AnimatedLogo(animation: animation);
+  Widget build(BuildContext context) {
+    return GrowTransition(
+      child: const LogoWidget(),
+      animation: animation,
+    );
+  }
   @override
   void dispose() {
     controller.dispose();
     super.dispose();
   }
 }

源代码： animate4

App source: animate4

同步动画

Simultaneous animations

在这部分内容中，您会根据监控动画过程 (animate3) 创建示例，该示例将使用 AnimatedWidget 持续进行动画。可以用在需要对透明度进行从透明到不透明动画处理的情况。

In this section, you’ll build on the example from monitoring the progress of the animation (animate3), which used AnimatedWidget to animate in and out continuously. Consider the case where you want to animate in and out while the opacity animates from transparent to opaque.

每个补间动画控制一个动画的不同方面，例如：

Each tween manages an aspect of the animation. For example:

controller =
    AnimationController(duration: const Duration(seconds: 2), vsync: this);
sizeAnimation = Tween<double>(begin: 0, end: 300).animate(controller);
opacityAnimation = Tween<double>(begin: 0.1, end: 1).animate(controller);

通过 sizeAnimation.value 我们可以得到尺寸，通过 opacityAnimation.value 可以得到不透明度，但是 AnimatedWidget 的构造函数只读取单一的 Animation 对象。为了解决这个问题，该示例创建了一个 Tween 对象并计算确切值。

You can get the size with sizeAnimation.value and the opacity with opacityAnimation.value, but the constructor for AnimatedWidget only takes a single Animation object. To solve this problem, the example creates its own Tween objects and explicitly calculates the values.

修改 AnimatedLogo 来封装其 Tween 对象，以及其 build() 方法在母动画对象上调用 Tween.evaluate() 来计算所需的尺寸和不透明度值。下面的代码中将这些改动突出显示：

Change AnimatedLogo to encapsulate its own Tween objects, and its build() method calls Tween.evaluate() on the parent’s animation object to calculate the required size and opacity values. The following code shows the changes with highlights:

class AnimatedLogo extends AnimatedWidget {
  const AnimatedLogo({Key? key, required Animation<double> animation})
      : super(key: key, listenable: animation);

  // Make the Tweens static because they don't change.
  static final _opacityTween = Tween<double>(begin: 0.1, end: 1);
  static final _sizeTween = Tween<double>(begin: 0, end: 300);

  @override
  Widget build(BuildContext context) {
    final animation = listenable as Animation<double>;
    return Center(
      child: Opacity(
        opacity: _opacityTween.evaluate(animation),
        child: Container(
          margin: const EdgeInsets.symmetric(vertical: 10),
          height: _sizeTween.evaluate(animation),
          width: _sizeTween.evaluate(animation),
          child: const FlutterLogo(),
        ),
      ),
    );
  }
}

class LogoApp extends StatefulWidget {
  const LogoApp({Key? key}) : super(key: key);

  @override
  _LogoAppState createState() => _LogoAppState();
}

class _LogoAppState extends State<LogoApp> with SingleTickerProviderStateMixin {
  late Animation<double> animation;
  late AnimationController controller;

  @override
  void initState() {
    super.initState();
    controller =
        AnimationController(duration: const Duration(seconds: 2), vsync: this);
    animation = CurvedAnimation(parent: controller, curve: Curves.easeIn)
      ..addStatusListener((status) {
        if (status == AnimationStatus.completed) {
          controller.reverse();
        } else if (status == AnimationStatus.dismissed) {
          controller.forward();
        }
      });
    controller.forward();
  }

  @override
  Widget build(BuildContext context) => AnimatedLogo(animation: animation);

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }
}

源代码： animate5

App source: animate5

下面的步骤

Next steps

本指南是在 Flutter 中应用 Tweens 创建动画的基础介绍，还有很多其他类可供探索。比如指定 Tween 类，Material Design 特有的动画， ReverseAnimation，共享元素过渡（也称为 Hero 动画），物理模拟和 fling() 方法。关于最新的文档和示例可参见动画效果介绍。

This tutorial gives you a foundation for creating animations in Flutter using Tweens, but there are many other classes to explore. You might investigate the specialized Tween classes, animations specific to Material Design, ReverseAnimation, shared element transitions (also known as Hero animations), physics simulations and fling() methods. See the animations landing page for the latest available documents and examples.

隐式动画

文档
Documentation
聚焦 Flutter 视频
Flutter in Focus videos
The Boring Show
每周 Widget 视频
Widget of the Week videos

通过 Flutter 的动画库，你可以为 UI 中的 widgets 添加动作并创造视觉效果。有些库包含各种各样可以帮你管理动画的 widget。这些 widgets 被统称为 隐式动画 或 隐式动画 widget，其名字来源于它们所实现的 ImplicitlyAnimatedWidget 类。下列资源提供了许多在 Flutter 中学习使用隐式动画的方法。

With Flutter’s animation library, you can add motion and create visual effects for the widgets in your UI. One part of the library is an assortment of widgets that manage animations for you. These widgets are collectively referred to as implicit animations, or implicitly animated widgets, deriving their name from the ImplicitlyAnimatedWidget class that they implement. The following set of resources provide many ways to learn about implicit animations in Flutter.

文档

Documentation

隐式动画 codelab
跳转至代码！ Codelab 使用交互式示例和分布介绍来教你学会如何使用隐式动画。

Implicit animations codelab
Jump right into the code! This codelab uses interactive examples and step-by-step instructions to teach you how to use implicit animations.

AnimatedContainer 示例
 Flutter cookbook 中针对如何使用 AnimatedContainer 隐式动画 widget 进行了手把手的指导。

AnimatedContainer sample
A step-by-step recipe from the Flutter cookbook for using the AnimatedContainer implicitly animated widget.

ImplicitlyAnimatedWidget API 页面
所有隐式动画都扩展了 ImplicitlyAnimatedWidget 类。

ImplicitlyAnimatedWidget API page
All implicit animations extend the ImplicitlyAnimatedWidget class.

聚焦 Flutter 视频

Flutter in Focus videos

聚焦 Flutter 视频以 5 到 10 分钟的实战代码为特点，涵盖了每个 Flutter 开发人员都需要从头到尾了解的技术。下列视频涵盖了所有与隐性动画相关的话题。

Flutter in Focus videos feature 5-10 minute tutorials with real code that cover techniques that every Flutter dev needs to know from top to bottom. The following videos cover topics that are relevant to implicit animations.

The Boring Show

观看《The Boring Show》，跟随谷歌工程师用 Flutter 从零开始构建应用程序。下面这一集涉及在一个新闻聚合器应用中使用隐式动画。

Watch the Boring Show to follow Google Engineers build apps from scratch in Flutter. The following episode covers using implicit animations in a news aggregator app.

Widget of the Week videos

每周都有一个系列的动画短片，每个短片都展示了一个特定 widget 的核心功能。在大约六十秒的时间里，你将会看到每个 widget 的实战代码，以及关于它是如何工作的演示。下列「每周 Widget」视频涉及了隐含动画 widget 有：

A weekly series of short animated videos each showing the important features of one particular widget. In about 60 seconds, you’ll see real code for each widget with a demo about how it works. The following Widget of the Week videos cover implicitly animated widgets:

主动画 (Hero animations)

hero 动画基本结构
Basic structure of a hero animation
幕后
Behind the scenes
- 基本类
  Essential classes
标准 hero 动画
Standard hero animations
径向 hero 动画
Radial hero animations

你可能经常遇到 hero 动画。比如，页面上显示的代售商品列表。选择一件商品后，应用会跳转至包含更多细节以及“购买”按钮的新页面。在 Flutter 中，图像从当前页面转到另一个页面称为 hero 动画，相同的动作有时也被称为 共享元素过渡。

You’ve probably seen hero animations many times. For example, a screen displays a list of thumbnails representing items for sale. Selecting an item flies it to a new screen, containing more details and a “Buy” button. Flying an image from one screen to another is called a hero animation in Flutter, though the same motion is sometimes referred to as a shared element transition.

下面的一分钟视频介绍了 Hero widget：

You might want to watch this one-minute video introducing the Hero widget:

这个指南演示了如何创建标准 hero 动画，以及 hero 动画如何在飞行过程中将图像形状由圆形变成正方形。

This guide demonstrates how to build standard hero animations, and hero animations that transform the image from a circular shape to a square shape during flight.

您可以在 Flutter 中使用 Hero widgets 创建这个动画。当 hero 动画从原页面到目标页面，目标页面（减去 hero）淡入视野。可以说，heroes 是 UI 的一小部分，就像图像，两个页面有共同之处。从用户的角度来说，hero 在页面间「飞翔」。本指南展示如何创建如下 hero 动画：

You can create this animation in Flutter with Hero widgets. As the hero animates from the source to the destination route, the destination route (minus the hero) fades into view. Typically, heroes are small parts of the UI, like images, that both routes have in common. From the user’s perspective the hero “flies” between the routes. This guide shows how to create the following hero animations:

标准 hero 动画

Standard hero animations

一个 标准 hero 动画 使 hero 从一页飞至新页面，通常以不同大小到达不同的目的地。

A standard hero animation flies the hero from one route to a new route, usually landing at a different location and with a different size.

下面的视频（慢放）演示了一个典型示例。点击页面中间的 flippers，它将飞至一个新的蓝色页面的左上角，并缩小。点击蓝色页面中的 flippers（或者使用设备的回到前页手势），它将返回原页面。

The following video (recorded at slow speed) shows a typical example. Tapping the flippers in the center of the route flies them to the upper left corner of a new, blue route, at a smaller size. Tapping the flippers in the blue route (orusing the device’s back-to-previous-route gesture) flies the flippers back to the original route.

径向 hero 动画

Radial hero animations

在 径向 hero 动画 中，随着 hero 在页面间飞翔，它的形状也会有圆形变成矩形。

In radial hero animation, as the hero flies between routes its shape appears to change from circular to rectangular.

下面的视频（慢放）演示了一个径向 hero 动画的示例。开始，一排三个圆形的图像在页面底部。点击任意圆形图像，其飞至新页面，并变成正方形。点击正方形图像，hero 返回至原页面，并变回圆形。

The following video (recorded at slow speed), shows an example of a radial hero animation. At the start, a row of three circular images appears at the bottom of the route. Tapping any of the circular images flies that image to a new route that displays it with a square shape. Tapping the square image flies the hero back to the original route, displayed with a circular shape.

在学习标准或径向 hero 动画之前，请阅读 hero 动画基本结构来学习如何构建 hero 动画代码，以及幕后来了解 Flutter 如何显示一个 hero 动画。

Before moving to the sections specific to standard or radial hero animations, read basic structure of a hero animation to learn how to structure hero animation code, and behind the scenes to understand how Flutter performs a hero animation.

hero 动画基本结构

Basic structure of a hero animation

要点列表

What's the point?

在不同页面分别使用两个 hero widgets，同时使用配对的标签来实现动画。
Use two hero widgets in different routes but with matching tags to implement the animation.
Navigator 管理含有 app 页面的堆栈。
The Navigator manages a stack containing the app’s routes.
推送一个页面或弹出一个 Navigator 堆栈中的页面会触发动画。
Pushing a route on or popping a route from the Navigator’s stack triggers the animation.
Flutter 框架设置了一个 RectTween 类，用来定义 hero 从原页面飞至目标页面的边界。在飞翔过程中，hero 移动到一个应用图层，这样它可以在两个页面上方显示。
The Flutter framework calculates a rectangle tween, RectTween that defines the hero’s boundary as it flies from the source to the destination route. During its flight, the hero is moved to an application overlay, so that it appears on top of both routes.

Hero 动画需要使用两个 Hero widgets 来实现：一个用来在原页面中描述 widget，另一个在目标页面中描述 widget。从用户角度来说，hero 似乎是分享的，只有程序员需要了解实施细节。

Hero animations are implemented using two Hero widgets: one describing the widget in the source route, and another describing the widget in the destination route. From the user’s point of view, the hero appears to be shared, and only the programmer needs to understand this implementation detail.

Hero 动画代码有如下结构：

Hero animation code has the following structure:

定义一个起始 Hero widget，被称为 source hero。该 hero 指定图形表示（通常是图像），以及识别标签，并且在由原页面定义的当前显示的 widget 树中。
Define a starting Hero widget, referred to as the source hero. The hero specifies its graphical representation (typically an image), and an identifying tag, and is in the currently displayed widget tree as defined by the source route.
定义一个截至 Hero widget，被称为 destination hero。该 hero 也指定图形表示，并与 source hero 使用同样的标签。 这是基本，两个 hero widgets 要创建相同的标签，通常是代表基础数据的对象。为了获得最佳效果，heroes 应该有几乎完全相同的 widget 树。
Define an ending Hero widget, referred to as the destination hero. This hero also specifies its graphical representation, and the same tag as the source hero. It’s essential that both hero widgets are created with the same tag, typically an object that represents the underlying data. For best results, the heroes should have virtually identical widget trees.
创建一个含有 destination hero 的页面。目标页面定义了动画结束时应有的 widget 树。
Create a route that contains the destination hero. The destination route defines the widget tree that exists at the end of the animation.
通过推送目标页面到 Navigator 堆栈来触发动画。 Navigator 推送并弹出操作触发原页面和目标页面中含有配对标签 heroes 的 hero 动画。
Trigger the animation by pushing the destination route on the Navigator’s stack. The Navigator push and pop operations trigger a hero animation for each pair of heroes with matching tags in the source and destination routes.

Flutter 设置了 tween 用来界定 Hero 从起点到终点的界限（插入大小和位置），并在图层上执行动画。

Flutter calculates the tween that animates the Hero’s bounds from the starting point to the endpoint (interpolating size and position), and performs the animation in an overlay.

下一章节将更详细地介绍 Flutter 的过程。

The next section describes Flutter’s process in greater detail.

幕后

Behind the scenes

下面将介绍 Flutter 如何执行一个页面到另一页面的过渡。

在过渡之前 source hero 出现在原页面中

The following describes how Flutter performs the transition from one route to another.

过渡前，source hero 在原页面的 widget 树中等待。而目标页面此时并不存在，图层也是空的。

Before transition, the source hero waits in the source route’s widget tree. The destination route does not yet exist, and the overlay is empty.

过渡开始

推送一个页面到 Navigator 来触发动画。t=0.0 时，Flutter 执行如下动作：

Pushing a route to the Navigator triggers the animation. At t=0.0, Flutter does the following:

使用 Material motion spec 中介绍的曲线运动计算 destination hero 路径，后台运行。 Flutter 限制知道 hero 应在何处终止。
Calculates the destination hero’s path, offscreen, using the curved motion as described in the Material motion spec. Flutter now knows where the hero ends up.
将 destination hero 放到图层，与 source hero 相同的位置和大小。添加一个 hero 到图层改变其 Z 轴的顺序，这样才可以出现在所有页面的上面。
Places the destination hero in the overlay, at the same location and size as the source hero. Adding a hero to the overlay changes its Z-order so that it appears on top of all routes.
将 source hero 移至后台运行。
Moves the source hero offscreen.

The hero flies in the overlay to its final position and size (hero 飞入图层到达其最终位置和大小)

hero 飞翔时，它的矩形边界使用 Hero 的 createRectTween 属性中特定的 Tween<Rect> 进行动画。默认情况下，Flutter 使用 MaterialRectArcTween 的示例，它沿着一个曲线路径设置矩形对角动画。（参考径向 hero 动画，该示例使用了不同的补间动画）

As the hero flies, its rectangular bounds are animated using Tween<Rect>, specified in Hero’s createRectTween property. By default, Flutter uses an instance of MaterialRectArcTween, which animates the rectangle’s opposing corners along a curved path. (See Radial hero animations for an example that uses a different Tween animation.)

When the transition is complete, the hero is moved from the overlay to the destination route (当过渡完成时，hero 从图层移动到目的页面)

当飞翔完成时：

When the flight completes:

Flutter 将 hero widget 从图层移动到目标页面。图层现在是空的。
Flutter moves the hero widget from the overlay to the destination route. The overlay is now empty.
destination hero 出现在目标图层的最终位置。
The destination hero appears in its final position in the destination route.
source hero 被储存到原页面中。
The source hero is restored to its route.

弹出的页面执行同样的过程，hero 动画回到原页面并回复原来大小和位置。

Popping the route performs the same process, animating the hero back to its size and location in the source route.

基本类

Essential classes

本指南中的示例使用了如下类来实现 hero 动画：

The examples in this guide use the following classes to implement hero animations:

Hero
从原页面飞到目标页面的 widget。定义一个原页面的 Hero 和另一个目标页面的 Hero，并设置相同的标签。 Flutter 为成对的含有匹配标签的 heroes 设置动画。

Hero
The widget that flies from the source to the destination route. Define one Hero for the source route and another for the destination route, and assign each the same tag. Flutter animates pairs of heroes with matching tags.

Inkwell
指定点击 hero 时发生什么。 InkWell 的 onTap() 方法可以创建新页面并推送至 Navigator 的堆栈。

Inkwell
Specifies what happens when tapping the hero. The InkWell’s onTap() method builds the new route and pushes it to the Navigator’s stack.

Navigator
Navigator 管理一个页面堆栈。推送或弹出 Navigator 堆栈中的页面触发动画。

Navigator
The Navigator manages a stack of routes. Pushing a route on or popping a route from the Navigator’s stack triggers the animation.

Route
指定屏幕或页面。除最基本的应用程序外，大部分含有多页面。

Route
Specifies a screen or page. Most apps, beyond the most basic, have multiple routes.

标准 hero 动画

Standard hero animations

标准 hero 动画代码

Standard hero animation code

下面的每个示例都演示了一个图形从一页面飞至另一页面。本指南详细介绍第一个例子。

Each of the following examples demonstrates flying an image from one route to another. This guide describes the first example.

hero_animation
将 hero 代码封装到自定义的 PhotoHero widget 中。沿 Material motion spec 中介绍的曲线路径设置 hero 动作的动画。

hero_animation
Encapsulates the hero code in a custom PhotoHero widget. Animates the hero’s motion along a curved path, as described in the Material motion spec.

basic_hero_animation
直接使用 hero widget。这个基础示例仅供参考，本指南中无详细介绍。

basic_hero_animation
Uses the hero widget directly. This more basic example, provided for your reference, isn’t described in this guide.

然后呢？

What’s going on?

使用 Flutter 的 hero widget 可以轻松实现图像由一个页面飞至另一个。当使用 MaterialPageRoute 指定新页面时，图像将沿 Material Design motion spec 中介绍的曲线路径飞翔。

Flying an image from one route to another is easy to implement using Flutter’s hero widget. When using MaterialPageRoute to specify the new route, the image flies along a curved path, as described by the Material Design motion spec.

创建一个新的 Flutter 示例并使用来自 hero_animation 的文件更新。

Create a new Flutter example and update it using the files from the hero_animation.

运行示例：

To run the example:

点击主页的图片使图像飞至新页面并在不同位置以不同规格显示相同图片。
Tap on the home route’s photo to fly the image to a new route showing the same photo at a different location and scale.
点击图像或使用设备的回到前页手势返回之前页面。
Return to the previous route by tapping the image, or by using the device’s back-to-the-previous-route gesture.
可以使用 timeDilation 属性来减缓过渡。
You can slow the transition further using the timeDilation property.

PhotoHero 类

PhotoHero class

自定义的 PhotoHero 类保留了 hero 以及其大小，图像，和点击时的动作。PhotoHero 创建如下 widget 树：

The custom PhotoHero class maintains the hero, and its size, image, and behavior when tapped. The PhotoHero builds the following widget tree:

代码如下：

Here’s the code:

class PhotoHero extends StatelessWidget {
  const PhotoHero({ Key key, this.photo, this.onTap, this.width }) : super(key: key);

  final String photo;
  final VoidCallback onTap;
  final double width;

  Widget build(BuildContext context) {
    return SizedBox(
      width: width,
      child: Hero(
        tag: photo,
        child: Material(
          color: Colors.transparent,
          child: InkWell(
            onTap: onTap,
            child: Image.asset(
              photo,
              fit: BoxFit.contain,
            ),
          ),
        ),
      ),
    );
  }
}

重要信息：

Key information:

当 HeroAnimation 作为应用程序的主页属性时，起始页面由 MaterialApp 隐式推送。
The starting route is implicitly pushed by MaterialApp when HeroAnimation is provided as the app’s home property.
InkWell 裹挟图像，使得为 source hero 和 destination hero 添加点击动作变得简单。
An InkWell wraps the image, making it trivial to add a tap gesture to the both the source and destination heroes.
用透明色定义 Material widget 使图片在飞至目标页时可以从背景中“弹出”。
Defining the Material widget with a transparent color enables the image to “pop out” of the background as it flies to its destination.
SizedBox 指定动画起始和结束时 hero 的大小。
The SizedBox specifies the hero’s size at the start and end of the animation.
设置图像的 fit 属性到 BoxFit.contain，可以确保在过渡过程中尽可能放大，且不改变长宽比例。
Setting the Image’s fit property to BoxFit.contain, ensures that the image is as large as possible during the transition without changing its aspect ratio.

HeroAnimation 类

HeroAnimation class

HeroAnimation 类可以创建 source PhotoHero 和 destination PhotoHero，并建立过渡。

The HeroAnimation class creates the source and destination PhotoHeroes, and sets up the transition.

代码如下：

Here’s the code:

class HeroAnimation extends StatelessWidget {
  Widget build(BuildContext context) {
    timeDilation = 5.0; // 1.0 means normal animation speed.

    return Scaffold(
      appBar: AppBar(
        title: const Text('Basic Hero Animation'),
      ),
      body: Center(
        child: PhotoHero(
          photo: 'images/flippers-alpha.png',
          width: 300.0,
          onTap: () {
            Navigator.of(context).push(MaterialPageRoute<void>(
              builder: (BuildContext context) {
                return Scaffold(
                  appBar: AppBar(
                    title: const Text('Flippers Page'),
                  ),
                  body: Container(
                    // The blue background emphasizes that it's a new route.
                    color: Colors.lightBlueAccent,
                    padding: const EdgeInsets.all(16.0),
                    alignment: Alignment.topLeft,
                    child: PhotoHero(
                      photo: 'images/flippers-alpha.png',
                      width: 100.0,
                      onTap: () {
                        Navigator.of(context).pop();
                      },
                    ),
                  ),
                );
              }
            ));
          },
        ),
      ),
    );
  }
}

重要信息：

Key information:

当用户点击含有 source hero 的 InkWell 时，代码使用 MaterialPageRoute 生成目标页面。并将目标页面推送至 Navigator 堆栈，触发动画。
When the user taps the InkWell containing the source hero, the code creates the destination route using MaterialPageRoute. Pushing the destination route to the Navigator’s stack triggers the animation.
Container 将 PhotoHero 置于目标页面左上角，AppBar 的下方。
The Container positions the PhotoHero in the destination route’s top-left corner, below the AppBar.
目标页 PhotoHero 的 onTap() 函数会弹出 Navigator 的堆栈，触发动画 Hero 飞回至原页面。
The onTap() method for the destination PhotoHero pops the Navigator’s stack, triggering the animation that flies the Hero back to the original route.
在调试时，可以使用 timeDilation 属性来减缓过渡。
Use the timeDilation property to slow the transition while debugging.

径向 hero 动画

Radial hero animations

hero 从一个页面飞至另一页的同时由圆形过渡到矩形，这是一个滑入效果，可使用 Hero widgets 来实现。要做到这一点，代码需要动画两个剪裁形状的交叉：一个圆形和一个正方形。整个动画中，圆形剪裁（和图片）由 minRadius 缩放到 maxRadius，而正方形剪裁保持大小不变。同时，图像从原页面飞至目标页面的相同位置。这个过渡的效果示例，请参见 Material motion spec 中的径向过渡。

Flying a hero from one route to another as it transforms from a circular shape to a rectangular shape is a slick effect that you can implement using Hero widgets. To accomplish this, the code animates the intersection of two clip shapes: a circle and a square. Throughout the animation, the circle clip (and the image) scales from minRadius to maxRadius, while the square clip maintains constant size. At the same time, the image flies from its position in the source route to its position in the destination route. For visual examples of this transition, see Radial transformation in the Material motion spec.

这个动画看起来复杂，但是您可以根据自身需要自定义范例。艰巨的工作已为您完成。

This animation might seem complex (and it is), but you can customize the provided example to your needs. The heavy lifting is done for you.

径向 hero 动画代码

Radial hero animation code

下面的每个示例都演示了一个径向 hero 动画。本指南详细介绍第一个示例。

Each of the following examples demonstrates a radial hero animation. This guide describes the first example.

radial_hero_animation
Material motion spec 中详细介绍了这个径向 hero 动画。

radial_hero_animation
A radial hero animation as described in the Material motion spec.

basic_radial_hero_animation
径向 hero 动画最简单的示例。目标页面没有 Scaffold, Card, Column, 或 Text。这个基本示例仅供参考，本指南不详述。

basic_radial_hero_animation
The simplest example of a radial hero animation. The destination route has no Scaffold, Card, Column, or Text. This basic example, provided for your reference, isn’t described in this guide.

radial_hero_animation_animate_rectclip
通过动画矩形剪裁大小，扩展径向 hero 动画。这个高阶示例亦供参考，本指南不详述。

radial_hero_animation_animate_rectclip
Extends radial_hero_animaton by also animating the size of the rectangular clip. This more advanced example, provided for your reference, isn’t described in this guide.

然后呢？

What’s going on?

下面的图表显示了在动画起始（t = 0.0）和结束（t = 1.0）时的剪裁图像。

The following diagram shows the clipped image at the beginning (t = 0.0), and the end (t = 1.0) of the animation.

Radial transformation from beginning to end

蓝色渐变（代表图像），表明剪裁形状交叉的位置。在过渡的开始，交叉的结果是圆形剪裁 (ClipOval)。在过渡过程中，ClipOval 由 minRadius 缩放至 maxRadius， ClipRect 则保持原尺寸。在过渡结束时，圆形和矩形剪裁的交集产生一个与 hero widget 相同大小的矩形。也就是说，在过渡结束时，图片已不再被剪裁。

The blue gradient (representing the image), indicates where the clip shapes intersect. At the beginning of the transition, the result of the intersection is a circular clip (ClipOval). During the transformation, the ClipOval scales from minRadius to maxRadius while the ClipRect maintains a constant size. At the end of the transition the intersection of the circular and rectangular clips yield a rectangle that’s the same size as the hero widget. In other words, at the end of the transition the image is no longer clipped.

创建一个新的 Flutter 示例并使用来自 radial_hero_animation 的文件更新。

Create a new Flutter example and update it using the files from the radial_hero_animation GitHub directory.

运行示例：

To run the example:

点击三个圆形缩略图中的任意一个，使图像变成位于新页面中间的一个较大的正方形，且覆盖原页面。
Tap on one of the three circular thumbnails to animate the image to a larger square positioned in the middle of a new route that obscures the original route.
点击图片或使用设备的返回手势，返回之前页面。
Return to the previous route by tapping the image, or by using the device’s back-to-the-previous-route gesture.
可以使用 timeDilation 属性来减缓过渡。
You can slow the transition further using the timeDilation property.

Photo 类

Photo class

Photo 类创建保存图像的 widget 树：

The Photo class builds the widget tree that holds the image:

class Photo extends StatelessWidget {
  Photo({ Key key, this.photo, this.color, this.onTap }) : super(key: key);

  final String photo;
  final Color color;
  final VoidCallback onTap;

  Widget build(BuildContext context) {
    return Material(
      // Slightly opaque color appears where the image has transparency.
      color: Theme.of(context).primaryColor.withOpacity(0.25),
      child: InkWell(
        onTap: onTap,
        child: Image.asset(
            photo,
            fit: BoxFit.contain,
          )
      ),
    );
  }
}

重要信息：

Key information:

Inkwell 捕捉点击动作。调用函数将 onTap() 函数传递给 Photo 的构造函数。
The Inkwell captures the tap gesture. The calling function passes the onTap() function to the Photo’s constructor.
飞翔过程中，InkWell 的飞溅效果会出现在它第一个 Material 祖先上。
During flight, the InkWell draws its splash on its first Material ancestor.
Material widget 有轻微不透明色，所以图像的透明部分会被渲染上颜色。这确保了圆形到正方形过渡，即使是透明的图像依然清晰可见。
The Material widget has a slightly opaque color, so the transparent portions of the image are rendered with color. This ensures that the circle-to-square transition is easy to see, even for images with transparency.
Photo 类的 widget 树中并不包含 Hero。为了使动画运行，hero需要包裹 RadialExpansion widget。
The Photo class does not include the Hero in its widget tree. For the animation to work, the hero wraps the RadialExpansion widget.

RadialExpansion 类

RadialExpansion class

RadialExpansion widget，demo 的核心，建立过渡过程中剪裁图像的 widget 树。剪裁的形状来自于圆形剪裁（飞翔过程中增长）和矩形剪裁（自始至终保持一致大小）的交集。

The RadialExpansion widget, the core of the demo, builds the widget tree that clips the image during the transition. The clipped shape results from the intersection of a circular clip (that grows during flight), with a rectangular clip (that remains a constant size throughout).

为此，它建立了如下 widget 树：

To do this, it builds the following widget tree:

代码如下：

Here’s the code:

class RadialExpansion extends StatelessWidget {
  RadialExpansion({
    Key key,
    this.maxRadius,
    this.child,
  }) : clipRectSize = 2.0 * (maxRadius / math.sqrt2),
       super(key: key);

  final double maxRadius;
  final clipRectSize;
  final Widget child;

  @override
  Widget build(BuildContext context) {
    return ClipOval(
      child: Center(
        child: SizedBox(
          width: clipRectSize,
          height: clipRectSize,
          child: ClipRect(
            child: child,  // Photo
          ),
        ),
      ),
    );
  }
}

重要信息：

Key information:

hero 包裹 RadialExpansion widget。
The hero wraps the RadialExpansion widget.
hero 飞翔时会改变大小，因为它限制了 child 的大小，所以 RadialExpansion widget 会改变大小以匹配。
As the hero flies, its size changes and, because it constrains its child’s size, the RadialExpansion widget changes size to match.
RadialExpansion 动画由两个重叠的剪裁创建。
The RadialExpansion animation is created by two overlapping clips.
这个示例用 MaterialRectCenterArcTween 定义了补间插值。 hero 动画的默认飞翔路径，利用 heroes 的角插值补间。这个方法会影响到径向过渡时 hero 的长宽比例，所以新的飞翔路径使用 MaterialRectCenterArcTween 方法，利用每个 hero 的中心点来插值补间。
The example defines the tweening interpolation using MaterialRectCenterArcTween. The default flight path for a hero animation interpolates the tweens using the corners of the heroes. This approach affects the hero’s aspect ratio during the radial transformation, so the new flight path uses MaterialRectCenterArcTween to interpolate the tweens using the center point of each hero.

代码如下：
Here’s the code:
```
static RectTween _createRectTween(Rect begin, Rect end) {
  return MaterialRectCenterArcTween(begin: begin, end: end);
}
```
Hero 的飞行路线仍然是一个弧线，但图像的长宽比将保持不变。
The hero’s flight path still follows an arc, but the image’s aspect ratio remains constant.

交织动画

一个交织动画的基础结构
Basic structure of a staggered animation

交织动画是一个简单的概念：视觉变化是随着一系列的动作发生，而不是一次性的动作。动画可能是纯粹顺序的，一个改变随着一个改变发生，动画也可能是部分或者全部重叠的。动画也可能有间隙，没有变化发生。

Staggered animations are a straightforward concept: visual changes happen as a series of operations, rather than all at once. The animation might be purely sequential, with one change occurring after the next, or it might partially or completely overlap. It might also have gaps, where no changes occur.

本指南展示如何在Flutter中构建交织动画。

This guide shows how to build a staggered animation in Flutter.

例子

Examples

本指南主要介绍 basic_staggered_animation 示例，您也可参考更复杂的例子：staggered_pic_selection。

This guide explains the basic_staggered_animation example. You can also refer to a more complex example, staggered_pic_selection.

basic_staggered_animation
展示一个单独的 widget 的一系列连续和重叠动画。轻触屏幕开始一个动画，改变不透明度，大小，形状、颜色和填充。

basic_staggered_animation
Shows a series of sequential and overlapping animations of a single widget. Tapping the screen begins an animation that changes opacity, size, shape, color, and padding.

staggered_pic_selection
展示从一个以三种大小显示的图像列表中删除一个图像。这个例子使用了两个动画控制器：一个用于控制图像的选择/取消选择, 一个用于控制删除图像. 选择/取消选择的动画是交织动画。 (想看到这种效果，你可能需要增加 timeDilation 的数值。) 选择最大的一个图像，它会收缩同时在一个在蓝色圆圈里显示一个对勾，然后，选择一个最小的图像，最大的图像会展开同时对勾消失。在最大的图像结束展开前，最小的图像会收缩并显示对勾。这个交织行为比较类似于你在 Google Photos 中看到的效果。

staggered_pic_selection
Shows deleting an image from a list of images displayed in one of three sizes. This example uses two animation controllers: one for image selection/deselection, and one for image deletion. The selection/deselection animation is staggered. (To see this effect, you might need to increase the timeDilation value.) Select one of the largest images—it shrinks as it displays a checkmark inside a blue circle. Next, select one of the smallest images—the large image expands as the checkmark disappears. Before the large image has finished expanding, the small image shrinks to display its checkmark. This staggered behavior is similar to what you might see in Google Photos.

以下视频演示了 basic_staggered_animation 所执行的动画：

The following video demonstrates the animation performed by basic_staggered_animation:

在这个视频中，你可以看到一个独立的 widget 的以下动画，以一个带边框的略微有圆角的蓝色矩形开始，这个矩形会按照以下顺序变化：

In the video, you see the following animation of a single widget, which begins as a bordered blue square with slightly rounded corners. The square runs through changes in the following order:

淡出
Fades in
扩大
Widens
向上移动同时变得更高
Becomes taller while moving upwards
变为一个有边框的圆圈
Transforms into a bordered circle
颜色变为橙色
Changes color to orange

向前运行之后，动画将反向运行。

After running forward, the animation runs in reverse.

一个交织动画的基础结构

Basic structure of a staggered animation

重点是什么？

What's the point?

所有的动画都是由相同同样的 AnimationController 驱动。
All of the animations are driven by the same AnimationController.
无论动画在真实时间中播放多长时间，控制器的值必须在 0.0 和 1.0 之间，包括 0.0 和 1.0。
Regardless of how long the animation lasts in real time, the controller’s values must be between 0.0 and 1.0, inclusive.
每个动画都有一个 Interval，值必须在 0.0 和 1.0 之间，包括 0.0 和 1.0。
Each animation has an Interval between 0.0 and 1.0, inclusive.
对于每一个间隔内产生动画的属性，创建一个 Tween。 Tween 可以指定该属性的开始值和结束值。
For each property that animates in an interval, create a Tween. The Tween specifies the start and end values for that property.
Tween 产生一个由控制器管理的 Animation 对象。
The Tween produces an Animation object that is managed by the controller.

下图展示了在 basic_staggered_animation 使用间隔的例子。你会注意到有以下特点：

The following diagram shows the Intervals used in the basic_staggered_animation example. You might notice the following characteristics:

透明度在时间轴的前 10% 发生变化。
The opacity changes during the first 10% of the timeline.
透明度的变化和宽度的变化之间有一个很小的间隔。
A tiny gap occurs between the change in opacity, and the change in width.
在时间轴的最后 25% 没有动画。
Nothing animates during the last 25% of the timeline.
增加填充使 widget 看起来向上上升。
Increasing the padding makes the widget appear to rise upward.
将圆角半径增加到 0.5，将圆角正方形变成一个圆。
Increasing the border radius to 0.5, transforms the square with rounded corners into a circle.
填充和高度的变化发生在相同的时间间隔内，但它们不必这么做。
The padding and height changes occur during the same exact interval, but they don’t have to.

Diagram showing the interval specified for each motion

设置这个动画：

To set up the animation:

创建一个 AnimationController 管理所有的 Animations。
Create an AnimationController that manages all of the Animations.
为每一个有动画的属性创建一个 Tween
Create a Tween for each property being animated.
- Tween 定义一个值的范围。
  The Tween defines a range of values.
- Tween 的 animate 方法需要 parent 控制器。同时生成一个动画为这个属性。
  The Tween’s animate method requires the parent controller, and produces an Animation for that property.
指定动画的 “curve” 属性的间隔
Specify the interval on the Animation’s curve property.

当控制动画的值发生变化时，新动画的值也随之变化值更改，触发 UI 更新。

When the controlling animation’s value changes, the new animation’s value changes, triggering the UI to update.

下面的代码为 width 属性创建了一个 tween。

The following code creates a tween for the width property.

它创建了一个 CurvedAnimation, 指定一个 eased curve。其他更多的预定的动画曲线请看 Curves。

It builds a CurvedAnimation, specifying an eased curve. See Curves for other available pre-defined animation curves.

width = Tween<double>(
  begin: 50.0,
  end: 150.0,
).animate(
  CurvedAnimation(
    parent: controller,
    curve: Interval(
      0.125, 0.250,
      curve: Curves.ease,
    ),
  ),
),

begin 和 end 的值不一定是 doubles。

The begin and end values don’t have to be doubles.

下面的代码为 borderRadius 属性创建一个 tween（控制矩形的圆角半径），使用 BorderRadius.circular()。

The following code builds the tween for the borderRadius property (which controls the roundness of the square’s corners), using BorderRadius.circular().

borderRadius = BorderRadiusTween(
  begin: BorderRadius.circular(4.0),
  end: BorderRadius.circular(75.0),
).animate(
  CurvedAnimation(
    parent: controller,
    curve: Interval(
      0.375, 0.500,
      curve: Curves.ease,
    ),
  ),
),

完整的交织动画

Complete staggered animation

像所有可交互的 widgets 一样，完整的动画包括一对 widget：一个无状态 widget 和一个有状态的 widget。

Like all interactive widgets, the complete animation consists of a widget pair: a stateless and a stateful widget.

无状态 widget 指定 Tweens，定义动画对象，提供一个 build() 方法，负责构建 widget 树的动画部分。

The stateless widget specifies the Tweens, defines the Animation objects, and provides a build() function responsible for building the animating portion of the widget tree.

有状态 widget 创建控制器，播放动画，同时构建 widget 树的非动画部分。当在屏幕上检测到一个点击时，动画开始。

The stateful widget creates the controller, plays the animation, and builds the non-animating portion of the widget tree. The animation begins when a tap is detected anywhere in the screen.

Full code for basic_staggered_animation’s main.dart

Stateless widget: StaggerAnimation

在无状态 widget 中，StaggerAnimation，the build() 函数实例化了一个 AnimatedBuilder—一个用于构建动画的通用 widget。 AnimatedBuilder 构建一个 widget 并使用 Tweens 的当前值配置它。这个例子创建一个名为 _buildAnimation() （实际更新 UI）的方法，并将其分配给其 builder 属性。AnimatedBuilder 监听来自动画控制器的通知，当值发生更改时，将 widget 树标记为 dirty。对于动画的每一个标记，值都会更新，导致调用 _buildAnimation()。

In the stateless widget, StaggerAnimation, the build() function instantiates an AnimatedBuilder—a general purpose widget for building animations. The AnimatedBuilder builds a widget and configures it using the Tweens’ current values. The example creates a function named _buildAnimation() (which performs the actual UI updates), and assigns it to its builder property. AnimatedBuilder listens to notifications from the animation controller, marking the widget tree dirty as values change. For each tick of the animation, the values are updated, resulting in a call to _buildAnimation().

class StaggerAnimation extends StatelessWidget {
  StaggerAnimation({ Key key, this.controller }) :

    // Each animation defined here transforms its value during the subset
    // of the controller's duration defined by the animation's interval.
    // For example the opacity animation transforms its value during
    // the first 10% of the controller's duration.

    opacity = Tween<double>(
      begin: 0.0,
      end: 1.0,
    ).animate(
      CurvedAnimation(
        parent: controller,
        curve: Interval(
          0.0, 0.100,
          curve: Curves.ease,
        ),
      ),
    ),

    // ... Other tween definitions ...

    super(key: key);

  final AnimationController controller;
  final Animation<double> opacity;
  final Animation<double> width;
  final Animation<double> height;
  final Animation<EdgeInsets> padding;
  final Animation<BorderRadius> borderRadius;
  final Animation<Color> color;

  // This function is called each time the controller "ticks" a new frame.
  // When it runs, all of the animation's values will have been
  // updated to reflect the controller's current value.
  Widget _buildAnimation(BuildContext context, Widget child) {
    return Container(
      padding: padding.value,
      alignment: Alignment.bottomCenter,
      child: Opacity(
        opacity: opacity.value,
        child: Container(
          width: width.value,
          height: height.value,
          decoration: BoxDecoration(
            color: color.value,
            border: Border.all(
              color: Colors.indigo[300],
              width: 3.0,
            ),
            borderRadius: borderRadius.value,
          ),
        ),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      builder: _buildAnimation,
      animation: controller,
    );
  }
}

Stateful widget: StaggerDemo

有状态的 widget, StaggerDemo，创建 AnimationController（控制所有动画的控制器），设定一个 2000 毫秒的周期。控制器播放一个动画，然后在 widget 树上创建一个无动画的部分。当在屏幕上检测到一个点击时，动画开始。动画向前运行，然后向后运行。

The stateful widget, StaggerDemo, creates the AnimationController (the one who rules them all), specifying a 2000 ms duration. It plays the animation, and builds the non-animating portion of the widget tree. The animation begins when a tap is detected in the screen. The animation runs forward, then backward.

class StaggerDemo extends StatefulWidget {
  @override
  _StaggerDemoState createState() => _StaggerDemoState();
}

class _StaggerDemoState extends State<StaggerDemo> with TickerProviderStateMixin {
  AnimationController _controller;

  @override
  void initState() {
    super.initState();

    _controller = AnimationController(
      duration: const Duration(milliseconds: 2000),
      vsync: this
    );
  }

  // ...Boilerplate...

  Future<void> _playAnimation() async {
    try {
      await _controller.forward().orCancel;
      await _controller.reverse().orCancel;
    } on TickerCanceled {
      // the animation got canceled, probably because it was disposed of
    }
  }

  @override
  Widget build(BuildContext context) {
    timeDilation = 10.0; // 1.0 is normal animation speed.
    return Scaffold(
      appBar: AppBar(
        title: const Text('Staggered Animation'),
      ),
      body: GestureDetector(
        behavior: HitTestBehavior.opaque,
        onTap: () {
          _playAnimation();
        },
        child: Center(
          child: Container(
            width: 300.0,
            height: 300.0,
            decoration: BoxDecoration(
              color: Colors.black.withOpacity(0.1),
              border: Border.all(
                color:  Colors.black.withOpacity(0.5),
              ),
            ),
            child: StaggerAnimation(
              controller: _controller.view
            ),
          ),
        ),
      ),
    );
  }
}

使用操作和快捷方式

Overview
- Why separate Actions from Intents?
- Why not use callbacks?
Shortcuts
- The ShortcutManager
Actions
Putting it together

This page describes how to bind physical keyboard events to actions in the user interface. For instance, to define keyboard shortcuts in your application, this page is for you.

Overview

For a GUI application to do anything, it has to have actions: users want to tell the application to do something. Actions are often simple functions that directly perform the action (such as set a value or save a file). In a larger application, however, things are more complex: the code for invoking the action, and the code for the action itself might need to be in different places. Shortcuts (key bindings) might need definition at a level that knows nothing about the actions they invoke.

That’s where Flutter’s actions and shortcuts system comes in. It allows developers to define actions that fulfill intents bound to them. In this context, an intent is a generic action that the user wishes to perform, and an Intent class instance represents these user intents in Flutter. An Intent can be general purpose, fulfilled by different actions in different contexts. An Action can be a simple callback (as in the case of the CallbackAction) or something more complex that integrates with entire undo/redo architectures (for example) or other logic.

Using Shortcuts Diagram

Shortcuts are key bindings that activate by pressing a key or combination of keys. The key combinations reside in a table with their bound intent. When the Shortcuts widget invokes them, it sends their matching intent to the actions subsystem for fulfillment.

To illustrate the concepts in actions and shortcuts, this article creates a simple app that allows a user to select and copy text in a text field using both buttons and shortcuts.

Why separate Actions from Intents?

You might wonder: why not just map a key combination directly to an action? Why have intents at all? This is because it is useful to have a separation of concerns between where the key mapping definitions are (often at a high level), and where the action definitions are (often at a low level), and because it is important to be able to have a single key combination map to an intended operation in an app, and have it adapt automatically to whichever action fulfills that intended operation for the focused context.

For instance, Flutter has an ActivateIntent widget that maps each type of control to its corresponding version of an ActivateAction (and that executes the code that activates the control). This code often needs fairly private access to do its work. If the extra layer of indirection that Intents provide didn’t exist, it would be necessary to elevate the definition of the actions to where the defining instance of the Shortcuts widget could see them, causing the shortcuts to have more knowledge than necessary about which action to invoke, and to have access to or provide state that it wouldn’t necessarily have or need otherwise. This allows your code to separate the two concerns to be more independent.

Intents configure an action so that the same action can serve multiple uses. An example of this is DirectionalFocusIntent, which takes a direction to move the focus in, allowing the DirectionalFocusAction to know which direction to move the focus. Just be careful: don’t pass state in the Intent that applies to all invocations of an Action: that kind of state should be passed to the constructor of the Action itself, to keep the Intent from needing to know too much.

Why not use callbacks?

You also might wonder: why not just use a callback instead of an Action object? The main reason is that it’s useful for actions to decide whether they are enabled by implementing isEnabled. Also, it is often helpful if the key bindings, and the implementation of those bindings, are in different places.

If indeed all that is needed is a callback, without all the complexity (or flexibility) of Actions and Shortcuts, you can already use a Focus widget for this. For example, here’s the implementation of Flutter’s simple CallbackShortcuts widget (available on the dev branch) that takes a map of activators and executes callbacks for them:

class CallbackShortcuts extends StatelessWidget {
  const CallbackShortcuts({
    Key? key,
    required this.bindings,
    required this.child,
  }) : super(key: key);

  final Map<ShortcutActivator, VoidCallback> bindings;
  final Widget child;

  @override
  Widget build(BuildContext context) {
    return Focus(
      onKey: (FocusNode node, RawKeyEvent event) {
        KeyEventResult result = KeyEventResult.ignored;
        // Activates all key bindings that match, returns handled if any handle it.
        for (final ShortcutActivator activator in bindings.keys) {
          if (activator.accepts(event, RawKeyboard.instance)) {
            bindings[activator]!.call();
            result = KeyEventResult.handled;
          }
        }
        return result;
      },
      child: child,
    );
  }
}

This may be all that is needed for some apps.

Shortcuts

As you’ll see below, actions are useful on their own, but the most common use case involves binding them to a keyboard shortcut. This is what the Shortcuts widget is for.

It is inserted into the widget hierarchy to define key combinations that represent the user’s intent when that key combination is pressed. To convert that intended purpose for the key combination into a concrete action, the Actions widget used to map the Intent to an Action. For instance, you can define a SelectAllIntent, and bind it to your own SelectAllAction or to your CanvasSelectAllAction, and from that one key binding, the system invokes either one, depending on which part of your application has focus. Let’s see how the key binding part works:

@override
Widget build(BuildContext context) {
  return Shortcuts(
    shortcuts: <LogicalKeySet, Intent>{
      LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyA):
          SelectAllIntent(),
    },
    child: Actions(
      dispatcher: LoggingActionDispatcher(),
      actions: <Type, Action<Intent>>{
        SelectAllIntent: SelectAllAction(model),
      },
      child: Builder(
        builder: (BuildContext context) => TextButton(
          child: const Text('SELECT ALL'),
          onPressed: Actions.handler<SelectAllIntent>(
            context,
            SelectAllIntent(),
          ),
        ),
      ),
    ),
  );
}

The map given to a Shortcuts widget maps a LogicalKeySet (or a ShortcutActivator, see note below) to an Intent instance. The logical key set defines a set of one or more keys, and the intent indicates the intended purpose of the keypress. The Shortcuts widget looks up keypresses in the map, to find an Intent instance, which it gives to the action’s invoke() method.

The ShortcutManager

The shortcut manager, a longer-lived object than the Shortcuts widget, passes on key events when it receives them. It contains the logic for deciding how to handle the keys, the logic for walking up the tree to find other shortcut mappings, and maintains a map of key combinations to intents.

While the default behavior of the ShortcutManager is usually desirable, the Shortcuts widget takes a ShortcutManager that you can subclass to customize its functionality.

For example, if you wanted to log each key that a Shortcuts widget handled, you could make a LoggingShortcutManager:

class LoggingShortcutManager extends ShortcutManager {
  @override
  KeyEventResult handleKeypress(BuildContext context, RawKeyEvent event) {
    final KeyEventResult result = super.handleKeypress(context, event);
    if (result == KeyEventResult.handled) {
      print('Handled shortcut $event in $context');
    }
    return result;
  }
}

Now, every time the Shortcuts widget handles a shortcut, it prints out the key event and relevant context.

Actions

Actions allow for the definition of operations that the application can perform by invoking them with an Intent. Actions can be enabled or disabled, and receive the intent instance that invoked them as an argument to allow configuration by the intent.

Defining actions

Actions, in their simplest form, are just subclasses of Action<Intent> with an invoke() method. Here’s a simple action that simply invokes a function on the provided model:

class SelectAllAction extends Action<SelectAllIntent> {
  SelectAllAction(this.model);

  final Model model;

  @override
  void invoke(covariant SelectAllIntent intent) => model.selectAll();
}

Or, if it’s too much of a bother to create a new class, use a CallbackAction:

CallbackAction(onInvoke: (Intent intent) => model.selectAll());

Once you have an action, you add it to your application using the Actions widget, which takes a map of Intent types to Actions:

@override
Widget build(BuildContext context) {
  return Actions(
    actions: <Type, Action<Intent>>{
      SelectAllIntent: SelectAllAction(model),
    },
    child: child,
  );
}

The Shortcuts widget uses the Focus widget’s context and Actions.invoke to find which action to invoke. If the Shortcuts widget doesn’t find a matching intent type in the first Actions widget encountered, it considers the next ancestor Actions widget, and so on, until it reaches the root of the widget tree, or finds a matching intent type and invokes the corresponding action.

Invoking Actions

The actions system has several ways to invoke actions. By far the most common way is through the use of a Shortcuts widget covered in the previous section, but there are other ways to interrogate the actions subsystem and invoke an action. It’s possible to invoke actions that are not bound to keys.

For instance, to find an action associated with an intent, you can use:

Action<SelectAllIntent>? selectAll =
    Actions.maybeFind<SelectAllIntent>(context);

This returns an Action associated with the SelectAllIntent type if one is available in the given context. If one isn’t available, it returns null. If an associated Action should always be available, then use find instead of maybeFind, which throws an exception when it doesn’t find a matching Intent type.

To invoke the action (if it exists), call:

Object? result;
if (selectAll != null) {
  result = Actions.of(context).invokeAction(selectAll, SelectAllIntent());
}

Combine that into one call with the following:

Object? result =
    Actions.maybeInvoke<SelectAllIntent>(context, SelectAllIntent());

Sometimes you want to invoke an action as a result of pressing a button or another control. Do this with the Actions.handler function, which creates a handler closure if the intent has a mapping to an enabled action, and returns null if it doesn’t, so that the button is disabled if there is no matching enabled action in the context:

@override
Widget build(BuildContext context) {
  return Actions(
    actions: <Type, Action<Intent>>{
      SelectAllIntent: SelectAllAction(model),
    },
    child: Builder(
      builder: (BuildContext context) => TextButton(
        child: const Text('SELECT ALL'),
        onPressed: Actions.handler<SelectAllIntent>(
          context,
          SelectAllIntent(controller: controller),
        ),
      ),
    ),
  );
}

The Actions widget only invokes actions when isEnabled(Intent intent) returns true, allowing the action to decide if the dispatcher should consider it for invocation. If the action isn’t enabled, then the Actions widget gives another enabled action higher in the widget hierarchy (if it exists) a chance to execute.

The previous example uses a Builder because Actions.handler and Actions.invoke (for example) only finds actions in the provided context, and if the example passes the context given to the build function, the framework starts looking above the current widget. Using a Builder allows the framework to find the actions defined in the same build function.

You can invoke an action without needing a BuildContext, but since the Actions widget requires a context to find an enabled action to invoke, you need to provide one, either by creating your own Action instance, or by finding one in an appropriate context with Actions.find.

To invoke the action, pass the action to the invoke method on an ActionDispatcher, either one you created yourself, or one retrieved from an existing Actions widget using the Actions.of(context) method. Check whether the action is enabled before calling invoke. Of course, you can also just call invoke on the action itself, passing an Intent, but then you opt out of any services that an action dispatcher might provide (like logging, undo/redo, and so on).

Action dispatchers

Most of the time, you just want to invoke an action, have it do its thing, and forget about it. Sometimes, however, you might want to log the executed actions.

This is where replacing the default ActionDispatcher with a custom dispatcher comes in. You pass your ActionDispatcher to the Actions widget, and it invokes actions from any Actions widgets below that one that doesn’t set a dispatcher of its own.

The first thing Actions does when invoking an action is look up the ActionDispatcher and pass the action to it for invocation. If there is none, it creates a default ActionDispatcher that simply invokes the action.

If you want a log of all the actions invoked, however, you can create your own LoggingActionDispatcher to do the job:

class LoggingActionDispatcher extends ActionDispatcher {
  @override
  Object? invokeAction(
    covariant Action<Intent> action,
    covariant Intent intent, [
    BuildContext? context,
  ]) {
    print('Action invoked: $action($intent) from $context');
    super.invokeAction(action, intent, context);
  }
}

Then you pass that to your top-level Actions widget:

@override
Widget build(BuildContext context) {
  return Actions(
    dispatcher: LoggingActionDispatcher(),
    actions: <Type, Action<Intent>>{
      SelectAllIntent: SelectAllAction(model),
    },
    child: Builder(
      builder: (BuildContext context) => TextButton(
        child: const Text('SELECT ALL'),
        onPressed: Actions.handler<SelectAllIntent>(
          context,
          SelectAllIntent(),
        ),
      ),
    ),
  );
}

This logs every action as it executes, like so:

flutter: Action invoked: SelectAllAction#906fc(SelectAllIntent#a98e3) from Builder(dependencies: _[ActionsMarker])

Putting it together

The combination of Actions and Shortcuts is powerful: you can define generic intents that map to specific actions at the widget level. Here’s a simple app that illustrates the concepts described above. The app creates a text field that also has “select all” and “copy to clipboard” buttons next to it. The buttons invoke actions to accomplish their work. All the invoked actions and shortcuts are logged.

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

/// A text field that also has buttons to select all the text and copy the
/// selected text to the clipboard.
class CopyableTextField extends StatefulWidget {
  const CopyableTextField({Key? key, required this.title}) : super(key: key);

  final String title;

  @override
  State<CopyableTextField> createState() => _CopyableTextFieldState();
}

class _CopyableTextFieldState extends State<CopyableTextField> {
  late TextEditingController controller = TextEditingController();

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Actions(
      dispatcher: LoggingActionDispatcher(),
      actions: <Type, Action<Intent>>{
        ClearIntent: ClearAction(controller),
        CopyIntent: CopyAction(controller),
        SelectAllIntent: SelectAllAction(controller),
      },
      child: Builder(builder: (BuildContext context) {
        return Scaffold(
          body: Center(
            child: Row(
              children: <Widget>[
                const Spacer(),
                Expanded(
                  child: TextField(controller: controller),
                ),
                IconButton(
                  icon: const Icon(Icons.copy),
                  onPressed:
                      Actions.handler<CopyIntent>(context, const CopyIntent()),
                ),
                IconButton(
                  icon: const Icon(Icons.select_all),
                  onPressed: Actions.handler<SelectAllIntent>(
                      context, const SelectAllIntent()),
                ),
                const Spacer(),
              ],
            ),
          ),
        );
      }),
    );
  }
}

/// A ShortcutManager that logs all keys that it handles.
class LoggingShortcutManager extends ShortcutManager {
  @override
  KeyEventResult handleKeypress(BuildContext context, RawKeyEvent event) {
    final KeyEventResult result = super.handleKeypress(context, event);
    if (result == KeyEventResult.handled) {
      print('Handled shortcut $event in $context');
    }
    return result;
  }
}

/// An ActionDispatcher that logs all the actions that it invokes.
class LoggingActionDispatcher extends ActionDispatcher {
  @override
  Object? invokeAction(
    covariant Action<Intent> action,
    covariant Intent intent, [
    BuildContext? context,
  ]) {
    print('Action invoked: $action($intent) from $context');
    super.invokeAction(action, intent, context);
  }
}

/// An intent that is bound to ClearAction in order to clear its
/// TextEditingController.
class ClearIntent extends Intent {
  const ClearIntent();
}

/// An action that is bound to ClearIntent that clears its
/// TextEditingController.
class ClearAction extends Action<ClearIntent> {
  ClearAction(this.controller);

  final TextEditingController controller;

  @override
  Object? invoke(covariant ClearIntent intent) {
    controller.clear();
  }
}

/// An intent that is bound to CopyAction to copy from its
/// TextEditingController.
class CopyIntent extends Intent {
  const CopyIntent();
}

/// An action that is bound to CopyIntent that copies the text in its
/// TextEditingController to the clipboard.
class CopyAction extends Action<CopyIntent> {
  CopyAction(this.controller);

  final TextEditingController controller;

  @override
  Object? invoke(covariant CopyIntent intent) {
    final String selectedString = controller.text.substring(
      controller.selection.baseOffset,
      controller.selection.extentOffset,
    );
    Clipboard.setData(ClipboardData(text: selectedString));
  }
}

/// An intent that is bound to SelectAllAction to select all the text in its
/// controller.
class SelectAllIntent extends Intent {
  const SelectAllIntent();
}

/// An action that is bound to SelectAllAction that selects all text in its
/// TextEditingController.
class SelectAllAction extends Action<SelectAllIntent> {
  SelectAllAction(this.controller);

  final TextEditingController controller;

  @override
  Object? invoke(covariant SelectAllIntent intent) {
    controller.selection = controller.selection.copyWith(
      baseOffset: 0,
      extentOffset: controller.text.length,
      affinity: controller.selection.affinity,
    );
  }
}

/// The top level application class.
///
/// Shortcuts defined here are in effect for the whole app,
/// although different widgets may fulfill them differently.
class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  static const String title = 'Shortcuts and Actions Demo';

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: title,
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: Shortcuts(
        manager: LoggingShortcutManager(),
        shortcuts: <LogicalKeySet, Intent>{
          LogicalKeySet(LogicalKeyboardKey.escape): const ClearIntent(),
          LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyC):
              const CopyIntent(),
          LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyA):
              const SelectAllIntent(),
        },
        child: const CopyableTextField(title: title),
      ),
    );
  }
}

void main() => runApp(const MyApp());

Understanding Flutter's focus system

Overview
- Focus use cases
Glossary
FocusNode and FocusScopeNode
- Best practices for creating FocusNode objects
- Unfocusing
Focus widget
FocusScope widget
FocusableActionDetector widget
Controlling focus traversal
- FocusTraversalGroup widget
- FocusTraversalPolicy
The focus manager

This article explains how to control where keyboard input is directed. If you are implementing an application that uses a physical keyboard, such as most desktop and web applications, this page is for you. If your app won’t be used with a physical keyboard, you can skip this.

Overview

Flutter comes with a focus system that directs the keyboard input to a particular part of an application. In order to do this, users “focus” the input onto that part of an application by tapping or clicking the desired UI element. Once that happens, text entered with the keyboard flows to that part of the application until the focus moves to another part of the application. Focus can also be moved by pressing a particular keyboard shortcut, which is typically bound to the Tab key, so it is sometimes called “tab traversal”.

This page explores the APIs used to perform these operations on a Flutter application, and how the focus system works. We have noticed that there is some confusion among developers about how to define and use FocusNode objects. If that describes your experience, skip ahead to the best practices for creating FocusNode objects.

Focus use cases

Some examples of situations where you might need to know how to use the focus system:

Receiving/handling key events
Implementing a custom component that needs to be focusable
Receiving notifications when the focus changes
Changing or defining the “tab order” of focus traversal in an application
Defining groups of controls that should be traversed together
Preventing some controls in an application from being focusable

Glossary

Below are terms, as Flutter uses them, for elements of the focus system. The various classes that implement some of these concepts are introduced below.

Focus tree - A tree of focus nodes that typically sparsely mirrors the widget tree, representing all the widgets that can receive focus.
Focus node - A single node in a focus tree. This node can receive the focus, and is said to “have focus” when it is part of the focus chain. It participates in handling key events only when it has focus.
Primary focus - The farthest focus node from the root of the focus tree that has focus. This is the focus node where key events start propagating to the primary focus node and its ancestors.
Focus chain - An ordered list of focus nodes that starts at the primary focus node and follows the branches of the focus tree to the root of the focus tree.
Focus scope - A special focus node whose job is to contain a group of other focus nodes, and allow only those nodes to receive focus. It contains information about which nodes were previously focused in its subtree.
Focus traversal - The process of moving from one focusable node to another in a predictable order. This is typically seen in applications when the user presses the Tab key to move to the next focusable control or field.

FocusNode and FocusScopeNode

The FocusNode and FocusScopeNode objects implement the mechanics of the focus system. They are long-lived objects (longer than widgets, similar to render objects) that hold the focus state and attributes so that they are persistent between builds of the widget tree. Together, they form the focus tree data structure.

They were originally intended to be developer-facing objects used to control some aspects of the focus system, but over time they have evolved to mostly implement details of the focus system. In order to prevent breaking existing applications, they still contain public interfaces for their attributes. But, in general, the thing for which they are most useful is to act as a relatively opaque handle, passed to a descendant widget in order to call requestFocus() on an ancestor widget, which requests that a descendant widget obtain focus. Setting of the other attributes is best managed by a Focus or FocusScope widget, unless you are not using them, or implementing your own version of them.

Best practices for creating FocusNode objects

Some dos and don’ts around using these objects include:

Don’t allocate a new FocusNode for each build. This can cause memory leaks, and occasionally causes a loss of focus when the widget rebuilds while the node has focus.
Do create FocusNode and FocusScopeNode objects in a stateful widget. FocusNode and FocusScopeNode need to be disposed of when you’re done using them, so they should only be created inside of a stateful widget’s state object, where you can override dispose to dispose of them.
Don’t use the same FocusNode for multiple widgets. If you do, the widgets will fight over managing the attributes of the node, and you probably won’t get what you expect.
Do set the debugLabel of a focus node widget to help with diagnosing focus issues.
Don’t set the onKey callback on a FocusNode or FocusScopeNode if they are being managed by a Focus or FocusScope widget. If you want an onKey handler, then add a new Focus widget around the widget subtree you would like to listen to, and set the onKey attribute of the widget to your handler. Set canRequestFocus: false on the widget if you also don’t want it to be able to take primary focus. This is because the onKey attribute on the Focus widget can be set to something else in a subsequent build, and if that happens, it overwrites the onKey handler you set on the node.
Do call requestFocus() on a node to request that it receives the primary focus, especially from an ancestor that has passed a node it owns to a descendant where you want to focus.
Do use focusNode.requestFocus(). It is not necessary to call FocusScope.of(context).requestFocus(focusNode). The focusNode.requestFocus() method is equivalent and more performant.

Unfocusing

There is an API for telling a node to “give up the focus”, named FocusNode.unfocus(). While it does remove focus from the node, it is important to realize that there really is no such thing as “unfocusing” all nodes. If a node is unfocused, then it must pass the focus somewhere else, since there is always a primary focus. The node that receives the focus when a node calls unfocus() is either the nearest FocusScopeNode, or a previously focused node in that scope, depending upon the disposition argument given to unfocus(). If you would like more control over where the focus goes when you remove it from a node, explicitly focus another node instead of calling unfocus(), or use the focus traversal mechanism to find another node with the focusInDirection, nextFocus, or previousFocus methods on FocusNode.

When calling unfocus(), the disposition argument allows two modes for unfocusing: UnfocusDisposition.scope and UnfocusDisposition.previouslyFocusedChild. The default is scope, which gives the focus to the nearest parent focus scope. This means that if the focus is thereafter moved to the next node with FocusNode.nextFocus, it starts with the “first” focusable item in the scope.

The previouslyFocusedChild disposition will search the scope to find the previously focused child and request focus on it. If there is no previously focused child, it is equivalent to scope.

The Focus widget owns and manages a focus node, and is the workhorse of the focus system. It manages the attaching and detaching of the focus node it owns from the focus tree, manages the attributes and callbacks of the focus node, and has static functions to enable discovery of focus nodes attached to the widget tree.

In its simplest form, wrapping the Focus widget around a widget subtree allows that widget subtree to obtain focus as part of the focus traversal process, or whenever requestFocus is called on the FocusNode passed to it. When combined with a gesture detector that calls requestFocus, it can receive focus when tapped or clicked.

You might pass a FocusNode object to the Focus widget to manage, but if you don’t, it creates its own. The main reason to create your own FocusNode is to be able to call requestFocus() on the node to control the focus from a parent widget. Most of the other functionality of a FocusNode is best accessed by changing the attributes of the Focus widget itself.

The Focus widget is used in most of Flutter’s own controls to implement their focus functionality.

Here is an example showing how to use the Focus widget to make a custom control focusable. It creates a container with text that reacts to receiving the focus.

import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);
  static const String _title = 'Focus Sample';

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: _title,
      home: Scaffold(
        appBar: AppBar(title: const Text(_title)),
        body: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: const <Widget>[MyCustomWidget(), MyCustomWidget()],
        ),
      ),
    );
  }
}

class MyCustomWidget extends StatefulWidget {
  const MyCustomWidget({Key? key}) : super(key: key);

  @override
  State<MyCustomWidget> createState() => _MyCustomWidgetState();
}

class _MyCustomWidgetState extends State<MyCustomWidget> {
  Color _color = Colors.white;
  String _label = 'Unfocused';

  @override
  Widget build(BuildContext context) {
    return Focus(
      onFocusChange: (bool focused) {
        setState(() {
          _color = focused ? Colors.black26 : Colors.white;
          _label = focused ? 'Focused' : 'Unfocused';
        });
      },
      child: Center(
        child: Container(
          width: 300,
          height: 50,
          alignment: Alignment.center,
          color: _color,
          child: Text(_label),
        ),
      ),
    );
  }
}

Key events

If you wish to listen for key events in a subtree, set the onKey attribute of the Focus widget to be a handler that either just listens to the key, or handles the key and stops its propagation to other widgets.

Key events start at the focus node with primary focus. If that node doesn’t return KeyEventResult.handled from its onKey handler, then its parent focus node is given the event. If the parent doesn’t handle it, it goes to its parent, and so on, until it reaches the root of the focus tree. If the event reaches the root of the focus tree without being handled, then it is returned to the platform to give to the next native control in the application (in case the Flutter UI is part of a larger native application UI). Events that are handled are not propagated to other Flutter widgets, and they are also not propagated to native widgets.

Here’s an example of a Focus widget that absorbs every key that its subtree doesn’t handle, without being able to be the primary focus:

@override
Widget build(BuildContext context) {
  return Focus(
    onKey: (FocusNode node, RawKeyEvent event) => KeyEventResult.handled,
    canRequestFocus: false,
    child: child,
  );
}

Focus key events are processed before text entry events, so handling a key event when the focus widget surrounds a text field prevents that key from being entered into the text field.

Here’s an example of a widget that won’t allow the letter “a” to be typed into the text field:

@override
Widget build(BuildContext context) {
  return Focus(
    onKey: (FocusNode node, RawKeyEvent event) {
      return (event.logicalKey == LogicalKeyboardKey.keyA)
          ? KeyEventResult.handled
          : KeyEventResult.ignored;
    },
    child: TextField(),
  );
}

If the intent is input validation, this example’s functionality would probably be better implemented using a TextInputFormatter, but the technique can still be useful: the Shortcuts widget uses this method to handle shortcuts before they become text input, for instance.

Controlling what gets focus

One of the main aspects of focus is controlling what can receive focus and how. The attributes canRequestFocus, skipTraversal, and descendantsAreFocusable control how this node and its descendants participate in the focus process.

If the skipTraversal attribute true, then this focus node doesn’t participate in focus traversal. It is still focusable if requestFocus is called on its focus node, but is otherwise skipped when the focus traversal system is looking for the next thing to focus on.

The canRequestFocus attribute, unsurprisingly, controls whether or not the focus node that this Focus widget manages can be used to request focus. If this attribute is false, then calling requestFocus on the node has no effect. It also implies that this node is skipped for focus traversal, since it can’t request focus.

The descendantsAreFocusable attribute controls whether the descendants of this node can receive focus, but still allows this node to receive focus. This attribute can be used to turn off focusability for an entire widget subtree. This is how the ExcludeFocus widget works: it’s just a Focus widget with this attribute set.

Autofocus

Setting the autofocus attribute of a Focus widget tells the widget to request the focus the first time the focus scope it belongs to is focused. If more than one widget has autofocus set, then it is arbitrary which one receives the focus, so try to only set it on one widget per focus scope.

The autofocus attribute only takes effect if there isn’t already a focus in the scope that the node belongs to.

Setting the autofocus attribute on two nodes that belong to different focus scopes is well defined: each one becomes the focused widget when their corresponding scopes are focused.

Change notifications

The Focus.onFocusChanged callback can be used to get notifications that the focus state for a particular node has changed. It notifies if the node is added to or removed from the focus chain, which means it gets notifications even if it isn’t the primary focus. If you only want to know if you have received the primary focus, check and see if hasPrimaryFocus is true on the focus node.

Obtaining the FocusNode

Sometimes, it is useful to obtain the focus node of a Focus widget to interrogate its attributes.

To access the focus node from an ancestor of the Focus widget, create and pass in a FocusNode as the Focus widget’s focusNode attribute. Because it needs to be disposed of, the focus node you pass needs to be owned by a stateful widget, so don’t just create one each time it is built.

If you need access to the focus node from the descendant of a Focus widget, you can call Focus.of(context) to obtain the focus node of the nearest Focuswidget to the given context. If you need to obtain the FocusNode of a Focus widget within the same build function, use a Builder to make sure you have the correct context. This is shown in the following example:

@override
Widget build(BuildContext context) {
  return Focus(
    child: Builder(
      builder: (BuildContext context) {
        final bool hasPrimary = Focus.of(context).hasPrimaryFocus;
        print('Building with primary focus: $hasPrimary');
        return const SizedBox(width: 100, height: 100);
      },
    ),
  );
}

Timing

One of the details of the focus system is that when focus is requested, it only takes effect after the current build phase completes. This means that focus changes are always delayed by one frame, because changing focus can cause arbitrary parts of the widget tree to rebuild, including ancestors of the widget currently requesting focus. Because descendants cannot dirty their ancestors, it has to happen between frames, so that any needed changes can happen on the next frame.

The FocusScope widget is a special version of the Focus widget that manages a FocusScopeNode instead of a FocusNode. The FocusScopeNode is a special node in the focus tree that serves as a grouping mechanism for the focus nodes in a subtree. Focus traversal stays within a focus scope unless a node outside of the scope is explicitly focused.

The focus scope also keeps track of the current focus and history of the nodes focused within its subtree. That way, if a node releases focus or is removed when it had focus, the focus can be returned to the node that had focus previously.

Focus scopes also serve as a place to return focus to if none of the descendants have focus. This allows the focus traversal code to have a starting context for finding the next (or first) focusable control to move to.

If you focus a focus scope node, it first attempts to focus the current, or most recently focused node in its subtree, or the node in its subtree that requested autofocus (if any). If there is no such node, it receives the focus itself.

The FocusableActionDetector is a widget that combines the functionality of Actions, Shortcuts, MouseRegion and a Focus widget to create a detector that defines actions and key bindings, and provides callbacks for handling focus and hover highlights. It is what Flutter controls use to implement all of these aspects of the controls. It is just implemented using the constituent widgets, so if you don’t need all of its functionality, you can just use the ones you need, but it is a convenient way to build these behaviors into your custom controls.

Controlling focus traversal

Once an application has the ability to focus, the next thing many apps want to do is to allow the user to control the focus using the keyboard or another input device. The most common example of this is “tab traversal” where the user presses the Tab key to go to the “next” control. Controlling what “next” means is the subject of this section. This kind of traversal is provided by Flutter by default.

In a simple grid layout, it’s fairly easy to decide which control is next. If you’re not at the end of the row, then it’s the one to the right (or left for right-to-left locales). If you are at the end of a row, it’s the first control in the next row. Unfortunately, applications are rarely laid out in grids, so more guidance is often needed.

The default algorithm in Flutter (ReadingOrderTraversalPolicy) for focus traversal is pretty good: It gives the right answer for most applications. However, there are always pathological cases, or cases where the context or design requires a different order than the one the default ordering algorithm arrives at. For those cases, there are other mechanisms for achieving the desired order.

The FocusTraversalGroup widget should be placed in the tree around widget subtrees that should be fully traversed before moving on to another widget or group of widgets. Just grouping widgets into related groups is often enough to resolve many tab traversal ordering problems. If not, the group can also be given a FocusTraversalPolicy to determine the ordering within the group.

The default ReadingOrderTraversalPolicy is usually sufficient, but in cases where more control over ordering is needed, an OrderedTraversalPolicy can be used. The order argument of the FocusTraversalOrder widget wrapped around the focusable components determines the order. The order can be any subclass of FocusOrder, but NumericFocusOrder and LexicalFocusOrder are provided.

If none of the provided focus traversal policies are sufficient for your application, you could also write your own policy and use it to determine any custom ordering you want.

Here’s an example of how to use the FocusTraversalOrder widget to traverse a row of buttons in the order TWO, ONE, THREE using NumericFocusOrder.

class OrderedButtonRow extends StatelessWidget {
  const OrderedButtonRow({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return FocusTraversalGroup(
      policy: OrderedTraversalPolicy(),
      child: Row(
        children: <Widget>[
          const Spacer(),
          FocusTraversalOrder(
            order: NumericFocusOrder(2.0),
            child: TextButton(
              child: const Text('ONE'),
              onPressed: () {},
            ),
          ),
          const Spacer(),
          FocusTraversalOrder(
            order: NumericFocusOrder(1.0),
            child: TextButton(
              child: const Text('TWO'),
              onPressed: () {},
            ),
          ),
          const Spacer(),
          FocusTraversalOrder(
            order: NumericFocusOrder(3.0),
            child: TextButton(
              child: const Text('THREE'),
              onPressed: () {},
            ),
          ),
          const Spacer(),
        ],
      ),
    );
  }
}

FocusTraversalPolicy

The FocusTraversalPolicy is the object that determines which widget is next, given a request and the current focus node. The requests (member functions) are things like findFirstFocus, findLastFocus, next, previous, and inDirection.

FocusTraversalPolicy is the abstract base class for concrete policies, like ReadingOrderTraversalPolicy, OrderedTraversalPolicy and the DirectionalFocusTraversalPolicyMixin classes.

In order to use a FocusTraversalPolicy, you give one to a FocusTraversalGroup, which determines the widget subtree in which the policy will be effective. The member functions of the class are rarely called directly: they are meant to be used by the focus system.

The focus manager

The FocusManager maintains the current primary focus for the system. It only has a few pieces of API that are useful to users of the focus system. One is the FocusManager.instance.primaryFocus property, which contains the currently focused focus node and is also accessible from the global primaryFocus field.

Other useful properties are FocusManager.instance.highlightMode and FocusManager.instance.highlightStrategy. These are used by widgets that need to switch between a “touch” mode and a “traditional” (mouse and keyboard) mode for their focus highlights. When a user is using touch to navigate, the focus highlight is usually hidden, and when they switch to a mouse or keyboard, the focus highlight needs to be shown again so they know what is focused. The hightlightStrategy tells the focus manager how to interpret changes in the usage mode of the device: it can either automatically switch between the two based on the most recent input events, or it can be locked in touch or traditional modes. The provided widgets in Flutter already know how to use this information, so you only need it if you’re writing your own controls from scratch. You can use addHighlightModeListener callback to listen for changes in the highlight mode.

点击、拖动和其他手势

指针
Pointers
手势
Gestures
- 为 widgets 添加手势检测
  Adding gesture detection to widgets
- 手势消歧处理
  Gesture disambiguation

这个章节将会讲解如何监听和响应 Flutter 的手势操作 gestures。典型的手势操作包括点击、拖动和缩放。

This document explains how to listen for, and respond to, gestures in Flutter. Examples of gestures include taps, drags, and scaling.

Flutter 中的手势有两个不同的层次：第一层是原始的指针指向事件，描述了屏幕上由触摸板、鼠标、指示笔等触发的指针的位置和移动。第二层包含 gestures，描述了由上述一个或多个指针移动组成的具有特殊语义的操作。

The gesture system in Flutter has two separate layers. The first layer has raw pointer events that describe the location and movement of pointers (for example, touches, mice, and styli) across the screen. The second layer has gestures that describe semantic actions that consist of one or more pointer movements.

指针

Pointers

Pointer 代表的是人机界面交互的原始数据。一共有四种指针事件：

Pointers represent raw data about the user’s interaction with the device’s screen. There are four types of pointer events:

PointerDownEvent
指针在特定位置与屏幕接触

PointerDownEvent
The pointer has contacted the screen at a particular location.

PointerMoveEvent
指针从屏幕的一个位置移动到另外一个位置

PointerMoveEvent
The pointer has moved from one location on the screen to another.

PointerUpEvent
指针与屏幕停止接触

PointerUpEvent
The pointer has stopped contacting the screen.

PointerCancelEvent
指针的输入已经不再指向此应用

PointerCancelEvent
Input from this pointer is no longer directed towards this app.

在指针下落事件中，框架做了一个 hit test 的操作确定与屏幕发生接触的位置上有哪些组件以及分发给最内部的组件去响应。事件会沿着组件树从这个最内部的组件向组件树的根部冒泡分发。并且不存在用于取消或停止指针事件进行进一步分发的机制。

On pointer down, the framework does a hit test on your app to determine which widget exists at the location where the pointer contacted the screen. The pointer down event (and subsequent events for that pointer) are then dispatched to the innermost widget found by the hit test. From there, the events bubble up the tree and are dispatched to all the widgets on the path from the innermost widget to the root of the tree. There is no mechanism for canceling or stopping pointer events from being dispatched further.

使用 Listener 可以在组件层直接监听指针事件。然而，一般情况下，请考虑使用下面的 gestures 替代。

To listen to pointer events directly from the widgets layer, use a Listener widget. However, generally, consider using gestures (as discussed below) instead.

手势

Gestures

Gesture 代表的是语义操作（比如点击、拖动、缩放）。通常由一系列单独的指针事件组成，甚至是一系列单独的指针组成。 Gesture 可以分发多种事件，对应着手势的生命周期（比如开始拖动、拖动更新、结束拖动）。

Gestures represent semantic actions (for example, tap, drag, and scale) that are recognized from multiple individual pointer events, potentially even multiple individual pointers. Gestures can dispatch multiple events, corresponding to the lifecycle of the gesture (for example, drag start, drag update, and drag end):

点击

Tap

onTapDown
指针在发生接触的屏幕的特定位置可能引发点击事件。

onTapDown
A pointer that might cause a tap has contacted the screen at a particular location.

onTapUp
指针使在屏幕的特定位置触发的点击事件停止。

onTapUp
A pointer that will trigger a tap has stopped contacting the screen at a particular location.

onTap
点击事件已经发生。

onTap
A tap has occurred.

onTapCancel
指针已经触发了 onTapDown，但是最终不会形成一个点击事件。

onTapCancel
The pointer that previously triggered the onTapDown will not end up causing a tap.

双击

Double tap

onDoubleTap
用户在屏幕的相同位置上快速点击了两次。

onDoubleTap
The user has tapped the screen at the same location twice in quick succession.

长按

Long press

onLongPress
指针在屏幕的相同位置上保持接触持续一长段时间。

onLongPress
A pointer has remained in contact with the screen at the same location for a long period of time.

纵向拖动

Vertical drag

onVerticalDragStart
指针和屏幕产生接触并可能开始纵向移动。

onVerticalDragStart
A pointer has contacted the screen and might begin to move vertically.

onVerticalDragUpdate
指针和屏幕产生接触，在纵向上发生移动并保持移动。

onVerticalDragUpdate
A pointer that is in contact with the screen and moving vertically has moved in the vertical direction.

onVerticalDragEnd
指针先前和屏幕产生了接触，以特定速度纵向移动，并且此后不会在屏幕接触上发生纵向移动。

onVerticalDragEnd
A pointer that was previously in contact with the screen and moving vertically is no longer in contact with the screen and was moving at a specific velocity when it stopped contacting the screen.

横向拖动

Horizontal drag

onHorizontalDragStart
指针和屏幕产生接触并可能开始横向移动。

onHorizontalDragStart
A pointer has contacted the screen and might begin to move horizontally.

onHorizontalDragUpdate
指针和屏幕产生接触，在横向上发生移动并保持移动。

onHorizontalDragUpdate
A pointer that is in contact with the screen and moving horizontally has moved in the horizontal direction.

onHorizontalDragEnd
指针先前和屏幕产生了接触，以特定速度横向移动，并且此后不会在屏幕接触上发生横向移动。

onHorizontalDragEnd
A pointer that was previously in contact with the screen and moving horizontally is no longer in contact with the screen and was moving at a specific velocity when it stopped contacting the screen.

移动

Pan

onPanStart
指针和屏幕产生接触并可能开始横向移动或者纵向移动。如果设置了 onHorizontalDragStart 或者 onVerticalDragStart，该回调方法会引发崩溃。

onPanStart
A pointer has contacted the screen and might begin to move horizontally or vertically. This callback causes a crash if onHorizontalDragStart or onVerticalDragStart is set.

onPanUpdate
指针和屏幕产生接触，在横向或者纵向上发生移动并保持移动。如果设置了 onHorizontalDragUpdate 或者 onVerticalDragUpdate，该回调方法会引发崩溃。

onPanUpdate
A pointer that is in contact with the screen and is moving in the vertical or horizontal direction. This callback causes a crash if onHorizontalDragUpdate or onVerticalDragUpdate is set.

onPanEnd
指针先前和屏幕产生了接触，并且以特定速度移动，此后不再在屏幕接触上发生移动。如果设置了 onHorizontalDragEnd 或者 onVerticalDragEnd，该回调方法会引发崩溃。

onPanEnd
A pointer that was previously in contact with screen is no longer in contact with the screen and is moving at a specific velocity when it stopped contacting the screen. This callback causes a crash if onHorizontalDragEnd or onVerticalDragEnd is set.

为 widgets 添加手势检测

Adding gesture detection to widgets

从组件层监听手势，需要用到 GestureDetector。

To listen to gestures from the widgets layer, use a GestureDetector.

如果使用 Material 风格的组件，其中的许多组件都能够支持响应点击或者手势事件。比如 IconButton 和 TextButton 响应了按压事件（点击事件）， ListView 响应了滚动事件。如果使用了上述组件，你也可以使用 InkWell 来实现点击的“水波纹”效果。

If you’re using Material Components, many of those widgets already respond to taps or gestures. For example, IconButton and TextButton respond to presses (taps), and ListView responds to swipes to trigger scrolling. If you are not using those widgets, but you want the “ink splash” effect on a tap, you can use InkWell.

手势消歧处理

Gesture disambiguation

在屏幕的指定位置上，可能有多个手势捕捉器。所有的手势捕捉器监听了指针输入流事件并判断出特定手势。 GestureDetector widget 能够基于手势的回调是否非空决定是否应该尝试去识别该手势。

At a given location on screen, there might be multiple gesture detectors. All of these gesture detectors listen to the stream of pointer events as they flow past and attempt to recognize specific gestures. The GestureDetector widget decides which gestures to attempt to recognize based on which of its callbacks are non-null.

当屏幕上的指定指针有多个手势识别器时，框架会通过给每个手势识别器加入 gesture arena 来处理手势消歧。 gesture arena，也称作手势竞技场，会利用下述规则确定哪个手势在竞争中胜出：

When there is more than one gesture recognizer for a given pointer on the screen, the framework disambiguates which gesture the user intends by having each recognizer join the gesture arena. The gesture arena determines which gesture wins using the following rules:

在任何时候，识别器都可以宣告失败并离开竞技场。如果竞技场中只有一个识别器，那么这个识别器就是胜者。
At any time, a recognizer can declare defeat and leave the arena. If there’s only one recognizer left in the arena, that recognizer is the winner.
在任何时候，任何识别器都可以宣告胜利，这将导致这个识别器胜出，其他识别器失败。
At any time, a recognizer can declare victory, which causes it to win and all the remaining recognizers to lose.

比如，当纵向拖动和横向拖动需要处理消歧，当指针下落事件发生时，纵向和横向识别器都会进入竞技场，观测指针移动事件。如果用户在横向上移动超过了特定像素，横向识别器会宣告胜利，手势也会被当作横向拖动处理。同样的，如果用户在纵向上移动超过了特定的像素，纵向识别器会宣告胜利。

For example, when disambiguating horizontal and vertical dragging, both recognizers enter the arena when they receive the pointer down event. The recognizers observe the pointer move events. If the user moves the pointer more than a certain number of logical pixels horizontally, the horizontal recognizer declares victory and the gesture is interpreted as a horizontal drag. Similarly, if the user moves more than a certain number of logical pixels vertically, the vertical recognizer declares victory.

手势竞技场在仅有一个横向（或者纵向）拖动识别器的时候是非常高效的。在此示例中，竞技场中只有一个横向识别器，横向拖动就能够被立即识别到，这意味着横向移动从第一个像素开始就能够被立即处理成横向拖动手势，而并不需要等待进一步的手势消歧处理。

The gesture arena is beneficial when there is only a horizontal (or vertical) drag recognizer. In that case, there is only one recognizer in the arena and the horizontal drag is recognized immediately, which means the first pixel of horizontal movement can be treated as a drag and the user won’t need to wait for further gesture disambiguation.

使用 sliver 实现出色的滑动效果

A sliver is a portion of a scrollable area that you can define to behave in a special way. You can use slivers to achieve custom scrolling effects, such as elastic scrolling.

For a free, instructor-led video workshop that also uses DartPad, check out the following video about using slivers:

Resources

For more information on implementing fancy scrolling effects in Flutter, see the following resources:

Slivers, Demystified: A free article on Medium that explains how to implement custom scrolling using the sliver classes.
SliverAppBar: A one-minute Widget-of-the-week video that gives an overview of the SliverAppBar widget.
SliverList and SliverGrid: A one-minute Widget-of-the-week video that gives an overview of the SliverList and SliverGrid widgets.
Slivers explained - Making dynamic layouts: A 50-minute episode of The Boring Show where Ian Hickson, Flutter’s Tech Lead, and Filip Hracek discuss the power of slivers.

API docs

Here some links to relevant API docs:

向应用添加闪屏页

iOS 启动页
iOS launch screen
Android 启动页
Android launch screen

Add Splash Screen Header

闪屏页（也称为启动页）是你的应用在启动时给用户的第一印象。它们就像是你的应用的基础，同时允许你在它展示的时间里，加载你的引擎和初始化你的应用。本指南将展示如何在 Flutter 编写的移动应用中恰当地使用闪屏页。

Splash screens (also known as launch screens) provide a simple initial experience while your mobile app loads. They set the stage for your application, while allowing time for the app engine to load and your app to initialize. This guide teaches you how to use splash screens appropriately on iOS and Android.

iOS 启动页

iOS launch screen

所有应用在交付到 Apple 应用商店之前必须使用 Xcode storyboard 以提供应用启动页面。

All apps submitted to the Apple App Store must use an Xcode storyboard to provide the app’s launch screen.

默认的 Flutter 模板包括一个名为 LaunchScreen.storyboard 的 Xcode storyboard，可以根据您的选择进行定制你自己的资源。默认情况下，storyboard 将显示空白图像，但你可以修改它。在项目根目录下执行 open ios/Runner.xcworkspace 打开 Flutter 应用程序的 Xcode 项目。然后从项目导航器中选择 Runner/Assets.xcassets，并将所需图像拖拽至 LaunchImage 图像集中。

The default Flutter template includes an Xcode storyboard named LaunchScreen.storyboard that can be customized as you see fit with your own assets. By default, the storyboard displays a blank image, but you can change this. To do so, open the Flutter app’s Xcode project by typing open ios/Runner.xcworkspace from the root of your app directory. Then select Runner/Assets.xcassets from the Project Navigator and drop in the desired images to the LaunchImage image set.

Apple 在人机接口指南部分中为发布启动页提供了详细的指南。

Apple provides detailed guidance for launch screens as part of the Human Interface Guidelines.

Android 启动页

Android launch screen

在 Android 中，你有两个可以分开控制的页面：在 Android 应用初始化时的 启动页，以及在 Flutter 初始化时的 闪屏页。

In Android, there are two separate screens that you can control: a launch screen shown while your Android app initializes, and a splash screen that displays while the Flutter experience initializes.

应用初始化

Initializing the app

所有 Android 应用在操作系统准备应用进程时都需要一定的初始化时间。因此 Android 提供了启动界面的概念，在应用初始化的时候显示 Drawable。

Every Android app requires initialization time while the operating system sets up the app’s process. Android provides the concept of a launch screen to display a Drawable while the app is initializing.

默认的 Flutter 项目模板定义了启动主题和启动背景。你可以在 styles.xml 中自定义一个主题，将一个 Drawable 配置给该主题的 windowBackground，它将作为启动页被展示。

The default Flutter project template includes a definition of a launch theme and a launch background. You can customize this by editing styles.xml, where you can define a theme whose windowBackground is set to the Drawable that should be displayed as the launch screen.

<style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">
    <item name="android:windowBackground">@drawable/launch_background</item>
</style>

定义一个普通主题

Define a normal theme

此外，在 styles.xml 中定义一个 普通主题，当启动页消失后，它会应用在 FlutterActivity 上。普通主题的背景仅仅展示非常短暂的时间，例如，当启动页消失后、设备方向改变或者 Activity 恢复期间。因此建议普通主题的背景颜色使用与 Flutter UI 主要背景颜色相似的纯色。

In addition, style.xml defines a normal theme to be applied to FlutterActivity after the launch screen is gone. The normal theme background only shows for a very brief moment after the splash screen disappears, and during orientation change and Activity restoration. Therefore, it’s recommended that the normal theme use a solid background color that looks similar to the primary background color of the Flutter UI.

<style name="NormalTheme" parent="@android:style/Theme.Black.NoTitleBar">
    <item name="android:windowBackground">@drawable/normal_background</item>
</style>

在 AndroidManifest.xml 中配置 FlutterActivity

Set up the FlutterActivity in AndroidManifest.xml

在 AndroidManifest.xml 中，将 FlutterActivity 的 theme 设置为启动主题，将元数据元素添加到所需的 FlutterActivity，以知会 Flutter 在适当的时机从启动主题切换到普通主题。

In AndroidManifest.xml, set the theme of FlutterActivity to the launch theme. Then, add a metadata element to the desired FlutterActivity to instruct Flutter to switch from the launch theme to the normal theme at the appropriate time.

<activity
    android:name=".MyActivity"
    android:theme="@style/LaunchTheme"
    // ...
    >
    <meta-data
        android:name="io.flutter.embedding.android.NormalTheme"
        android:resource="@style/NormalTheme"
        />
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
</activity>

如此一来，Android 应用程序就会在在初始化时展示对应的启动页面。

The Android app now displays the desired launch screen while the app initializes.

Android S

Android 12 (S)

请先查看 Android 闪屏页面了解如何在 Android S 上配置闪屏页。

See Android Splash Screens first on how to configure your splash screen on Android S.

确保 io.flutter.embedding.android.SplashScreenDrawable 未在 manifest 中设置，且 provideSplashScreen 也没有具体实现，这些 API 已被废弃。如此一来 Android 的闪屏页可以在应用启动时平滑过渡到 Flutter。

Make sure neither io.flutter.embedding.android.SplashScreenDrawable is set in your manifest, nor is provideSplashScreen implemented, as these APIs are deprecated. Doing so will cause the Android splash screen to fade smoothly into the Flutter when the app is launched.

某些应用可能希望在 Flutter 中继续显示 Android 闪屏页的最后一帧。例如，保持一帧的展示，同时 Dart 继续加载其他内容。想达到这样的效果，以下 API 可能有帮助：

Some apps may want to continue showing the last frame of the Android splash screen in Flutter. For example, this preserves the illusion of a single frame while additional loading continues in Dart. To achieve this, the following Android APIs may be helpful:

Java
Kotlin

import android.os.Build;
import android.os.Bundle;
import android.window.SplashScreenView;
import androidx.core.view.WindowCompat;
import io.flutter.embedding.android.FlutterActivity;

public class MainActivity extends FlutterActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // Aligns the Flutter view vertically with the window.
        WindowCompat.setDecorFitsSystemWindows(getWindow(), false);

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            // Disable the Android splash screen fade out animation to avoid
            // a flicker before the similar frame is drawn in Flutter.
            getSplashScreen()
                .setOnExitAnimationListener(
                    (SplashScreenView splashScreenView) -> {
                        splashScreenView.remove();
                    });
        }

        super.onCreate(savedInstanceState);
    }
}

import android.os.Build
import android.os.Bundle
import androidx.core.view.WindowCompat
import io.flutter.embedding.android.FlutterActivity

class MainActivity : FlutterActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    // Aligns the Flutter view vertically with the window.
    WindowCompat.setDecorFitsSystemWindows(getWindow(), false)

    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
      // Disable the Android splash screen fade out animation to avoid
      // a flicker before the similar frame is drawn in Flutter.
      splashScreen.setOnExitAnimationListener { splashScreenView -> splashScreenView.remove() }
    }

    super.onCreate(savedInstanceState)
  }
}

然后你可以重新实现 Flutter 的第一帧，将元素摆放在与 Android 闪屏页相同的位置。

Then, you can reimplement the first frame in Flutter that shows elements of your Android splash screen in the same positions on screen.

迁移 Manifest 和 Activity 中自定义的闪屏

Migrating from Manifest / Activity defined custom splash screens

在 Flutter 2.5 之前，Flutter 的 Android 应用要么是在 manifest 中设置 io.flutter.embedding.android.SplashScreenDrawable，要么是在 Flutter Activity 中实现 provideSplashScreen。这会导致在 Android 的启动页和 Flutter 的第一帧绘制之间，有短暂的空隙。这样的处理方法已被废弃，Flutter 现在会将 Android 的启动页保持到 Flutter 的第一帧渲染完成。开发者们可以直接删除这些 API 的使用。

Previously, Android Flutter apps would either set io.flutter.embedding.android.SplashScreenDrawable in their application manifest, or implement provideSplashScreen within their Flutter Activity. This would be shown momentarily in between the time after the Android launch screen is shown and when Flutter has drawn the first frame. This is no longer needed and is deprecated – Flutter now automatically keeps the Android launch screen displayed until Flutter has drawn the first frame. Developers should instead remove usage of these APIs.

借助 Flutter 上关于视觉、结构、平台和交互的 widgets，我们可以快速创建出色的应用程序。除了能够按照如下类别浏览 widgets，你还可以在 Flutter Widget 目录中查看所有的 widgets。

Create beautiful apps faster with Flutter’s collection of visual, structural, platform, and interactive widgets. In addition to browsing widgets by category, you can also see all the widgets in the widget index.

Accessibility

Make your app accessible.

查看

Animation and Motion

Bring animations to your app.

查看

Assets, Images, and Icons

Manage assets, display images, and show icons.

查看

Async

Async patterns to your Flutter application.

查看

Basics

Widgets you absolutely need to know before building your first Flutter app.

查看

Cupertino (iOS-style widgets)

Beautiful and high-fidelity widgets for current iOS design language.

查看

Input

Take user input in addition to input widgets in Material Components and Cupertino.

查看

Interaction Models

Respond to touch events and route users to different views.

查看

Layout

Arrange other widgets columns, rows, grids, and many other layouts.

查看

Material Components

Visual, behavioral, and motion-rich widgets implementing the Material Design guidelines.

查看

Painting and effects

These widgets apply visual effects to the children without changing their layout, size, or position.

查看

Scrolling

Scroll multiple widgets as children of the parent.

查看

Styling

Manage the theme of your app, makes your app responsive to screen sizes, or add padding.

查看

Text

Display and style text.

查看

状态 (State) 管理介绍

如果你早已熟悉响应式 App 中的状态管理，你可以跳过这个部分，不过这里也有一些关于状态 (State) 管理参考的信息供你查阅。

If you are already familiar with state management in reactive apps, you can skip this section, though you might want to review the list of different approaches.

A short animated gif that shows the workings of a simple declarative state management system. This is explained in full in one of the following pages. Here it's just a decoration.

当你使用 Futter 进行开发时，有时会需要在 app 的不同界面中共享应用程序的状态，在这里你可以找到许多有用的方案以及一些可以深思的问题。

As you explore Flutter, there comes a time when you need to share application state between screens, across your app. There are many approaches you can take, and many questions to think about.

在接下来的文档里，你将会学习一些基础的状态管理知识。

In the following pages, you will learn the basics of dealing with state in Flutter apps.

状态管理中的声明式编程思维

如果你是从命令式框架（例如 Android SDK 或者 iOS UIKit）转到 Flutter 应用，那么，你需要开始从一个新的角度来考虑 app 开发了。

If you’re coming to Flutter from an imperative framework (such as Android SDK or iOS UIKit), you need to start thinking about app development from a new perspective.

因此，很多在命令式框架下的假设可能并不适用于 Flutter。例如，在 Flutter 应用中这是可行的，重新构建你的部分界面，而不是直接去修改它。如果有需要的话，Flutter 甚至可以在每一帧上都很快做到这点。

Many assumptions that you might have don’t apply to Flutter. For example, in Flutter it’s okay to rebuild parts of your UI from scratch instead of modifying it. Flutter is fast enough to do that, even on every frame if needed.

Flutter 应用是 声明式 的，这也就意味着 Flutter 构建的用户界面就是应用的当前状态。

Flutter is declarative. This means that Flutter builds its user interface to reflect the current state of your app:

A mathematical formula of UI = f(state). 'UI' is the layout on the screen. 'f' is your build methods. 'state' is the application state.

当你的 Flutter 应用的状态发生改变时（例如，用户在设置界面中点击了一个开关选项）你改变了状态，这将会触发用户界面的重绘。去改变用户界面本身是没有必要的（例如 widget.setText ）—你改变了状态，那么用户界面将重新构建。

When the state of your app changes (for example, the user flips a switch in the settings screen), you change the state, and that triggers a redraw of the user interface. There is no imperative changing of the UI itself (like widget.setText)—you change the state, and the UI rebuilds from scratch.

在声明式 UI 介绍中你可以阅读更多有关声明式编程思维的信息。

Read more about the declarative approach to UI programming in the get started guide.

声明式的编程风格有许多好处。值得注意的是，用户界面任何状态的改变都只有一种编码途径。一旦给定任意状态，你就描述了用户界面应该长什么样，并且它就是这样。

The declarative style of UI programming has many benefits. Remarkably, there is only one code path for any state of the UI. You describe what the UI should look like for any given state, once—and that is it.

刚开始的时候，这种编码风格可能看起来不像命令式的那么直观。这也是本章为什么出现在这的原因。

At first, this style of programming might not seem as intuitive as the imperative style. This is why this section is here. Read on.

短时 (ephemeral) 和应用 (app) 状态的区别

短时状态
Ephemeral state
应用状态
App state
没有明确的规则
There is no clear-cut rule

本文将介绍应用 (app) 状态、短时 (ephemeral) 状态，以及在一个 Flutter 应用中你可以如何应用这两种状态。

This doc introduces app state, ephemeral state, and how you might manage each in a Flutter app.

广义上来讲，一个应用的状态就是当这个应用运行时存在于内存中的所有内容。这包括了应用中用到的资源，所有 Flutter 框架中有关用户界面、动画状态、纹理、字体以及其他等等的变量。这个对于状态广义的定义是有效的，但是它对于构建一个应用来说并不是很有用。

In the broadest possible sense, the state of an app is everything that exists in memory when the app is running. This includes the app’s assets, all the variables that the Flutter framework keeps about the UI, animation state, textures, fonts, and so on. While this broadest possible definition of state is valid, it’s not very useful for architecting an app.

首先，你不需要管理一些状态（例如纹理），框架本身会替你管理。所以对于状态的更有用的定义是 “当任何时候你需要重建你的用户界面时你所需要的数据”。其次，你需要自己管理的状态可以分为两种概念类型：短时 (ephemeral) 状态和应用 (app) 状态。

First, you don’t even manage some state (like textures). The framework handles those for you. So a more useful definition of state is “whatever data you need in order to rebuild your UI at any moment in time”. Second, the state that you do manage yourself can be separated into two conceptual types: ephemeral state and app state.

短时状态

Ephemeral state

短时状态（有时也称 用户界面 (UI) 状态 或者 局部状态）是你可以完全包含在一个独立 widget 中的状态。

Ephemeral state (sometimes called UI state or local state) is the state you can neatly contain in a single widget.

这是一个有点儿模糊的定义，这里有几个例子。

This is, intentionally, a vague definition, so here are a few examples.

一个 PageView 组件中的当前页面
current page in a PageView
一个复杂动画中当前进度
current progress of a complex animation
一个 BottomNavigationBar 中当前被选中的 tab
current selected tab in a BottomNavigationBar

widget 树中其他部分不需要访问这种状态。不需要去序列化这种状态，这种状态也不会以复杂的方式改变。

Other parts of the widget tree seldom need to access this kind of state. There is no need to serialize it, and it doesn’t change in complex ways.

换句话说，不需要使用状态管理架构（例如 ScopedModel, Redux）去管理这种状态。你需要用的只是一个 StatefulWidget。

In other words, there is no need to use state management techniques (ScopedModel, Redux, etc.) on this kind of state. All you need is a StatefulWidget.

在下方你可以看到一个底部导航栏中当前被选中的项目是如何被被保存在 _MyHomepageState 类的 _index 变量中。在这个例子中，_index 是一个短时状态。

Below, you see how the currently selected item in a bottom navigation bar is held in the _index field of the _MyHomepageState class. In this example, _index is ephemeral state.

class MyHomepage extends StatefulWidget {
  const MyHomepage({Key? key}) : super(key: key);

  @override
  _MyHomepageState createState() => _MyHomepageState();
}

class _MyHomepageState extends State<MyHomepage> {
  int _index = 0;

  @override
  Widget build(BuildContext context) {
    return BottomNavigationBar(
      currentIndex: _index,
      onTap: (newIndex) {
        setState(() {
          _index = newIndex;
        });
      },
      // ... items ...
    );
  }
}

在这里，使用 setState() 和一个在有状态 widget 的 State 类中的变量是很自然的。你的 app 中的其他部分不需要访问 _index。这个变量只会在 MyHomepage widget 中改变。而且，如果用户关闭并重启这个 app，你不会介意 _index 重置回 0.

Here, using setState() and a field inside the StatefulWidget’s State class is completely natural. No other part of your app needs to access _index. The variable only changes inside the MyHomepage widget. And, if the user closes and restarts the app, you don’t mind that _index resets to zero.

应用状态

App state

如果你想在你的应用中的多个部分之间共享一个非短时的状态，并且在用户会话期间保留这个状态，我们称之为应用状态（有时也称共享状态）。

State that is not ephemeral, that you want to share across many parts of your app, and that you want to keep between user sessions, is what we call application state (sometimes also called shared state).

应用状态的一些例子：

Examples of application state:

用户选项
User preferences
登录信息
Login info
一个社交应用中的通知
Notifications in a social networking app
一个电商应用中的购物车
The shopping cart in an e-commerce app
一个新闻应用中的文章已读/未读状态
Read/unread state of articles in a news app

为了管理应用状态，你需要研究你的选项。你的选择取决于你的应用的复杂度和限制，你的团队之前的经验以及其他方面。请继续阅读。

For managing app state, you’ll want to research your options. Your choice depends on the complexity and nature of your app, your team’s previous experience, and many other aspects. Read on.

没有明确的规则

There is no clear-cut rule

需要说明的是，你可以使用 State 和 setState() 管理你的应用中的所有状态。实际上Flutter团队在很多简单的示例程序（包括你每次使用 flutter create 命令创建的初始应用）中正是这么做的。

To be clear, you can use State and setState() to manage all of the state in your app. In fact, the Flutter team does this in many simple app samples (including the starter app that you get with every flutter create).

也可以用另外一种方式。比如，在一个特定的应用中，你可以指定底部导航栏中被选中的项目不是一个短时状态。你可能需要在底部导航栏类的外部来改变这个值，并在对话期间保留它。在种情况下 _index 就是一个应用状态。

It goes the other way, too. For example, you might decide that—in the context of your particular app—the selected tab in a bottom navigation bar is not ephemeral state. You might need to change it from outside the class, keep it between sessions, and so on. In that case, the _index variable is app state.

没有一个明确、普遍的规则来区分一个变量属于短时状态还是应用状态，有时你不得不在此之间重构。比如，刚开始你认为一些状态是短时状态，但随着应用不断增加功能，有些状态需要被改变为应用状态。

There is no clear-cut, universal rule to distinguish whether a particular variable is ephemeral or app state. Sometimes, you’ll have to refactor one into another. For example, you’ll start with some clearly ephemeral state, but as your application grows in features, it might need to be moved to app state.

因此，请有保留地遵循以下这张流程图：

For that reason, take the following diagram with a large grain of salt:

A flow chart. Start with 'Data'. 'Who needs it?'. Three options: 'Most widgets', 'Some widgets' and 'Single widget'. The first two options both lead to 'App state'. The 'Single widget' option leads to 'Ephemeral state'.

当我们就 React 的 setState 和 Redux 的 Store 哪个好这个问题问 Redux 的作者 Dan Abramov 时, 他如此回答:

When asked about React’s setState versus Redux’s store, the author of Redux, Dan Abramov, replied:

“经验原则是: 选择能够减少麻烦的方式”
“The rule of thumb is: Do whatever is less awkward.”

总之，在任何 Flutter 应用中都存在两种概念类型的状态，短时状态经常被用于一个单独 widget 的本地状态，通常使用 State 和 setState() 来实现。其他的是你的应用应用状态，在任何一个 Flutter 应用中这两种状态都有自己的位置。如何划分这两种状态取决于你的偏好以及应用的复杂度。

In summary, there are two conceptual types of state in any Flutter app. Ephemeral state can be implemented using State and setState(), and is often local to a single widget. The rest is your app state. Both types have their place in any Flutter app, and the split between the two depends on your own preference and the complexity of the app.

简单的应用状态管理

示例
Our example
提高状态的层级
Lifting state up
读取状态
Accessing the state
ChangeNotifier
ChangeNotifierProvider
Consumer
- Provider.of
把代码集成在一起
Putting it all together

现在大家已经了解了声明式的编程思维和短时 (ephemeral) 与应用 (app) 状态之间的区别，现在可以学习如何管理简单的全局应用状态。

Now that you know about declarative UI programming and the difference between ephemeral and app state, you are ready to learn about simple app state management.

在这里，我们打算使用 provider package。如果你是 Flutter 的初学者，而且也没有很重要的理由必须选择别的方式来实现（Redux、Rx、hooks 等等），那么这就是你应该入门使用的。provider 非常好理解而且不需要写很多代码。它也会用到一些在其它实现方式中用到的通用概念。

On this page, we are going to be using the provider package. If you are new to Flutter and you don’t have a strong reason to choose another approach (Redux, Rx, hooks, etc.), this is probably the approach you should start with. The provider package is easy to understand and it doesn’t use much code. It also uses concepts that are applicable in every other approach.

即便如此，如果你已经从其它响应式框架上积累了丰富的状态管理经验的话，那么可以在状态 (State) 管理参考中找到相关的 package 和教程。

That said, if you have a strong background in state management from other reactive frameworks, you can find packages and tutorials listed on the options page.

示例

Our example

为了演示效果，我们实现下面这个简单应用。

For illustration, consider the following simple app.

这个应用有两个独立的页面：一个类别页面和一个购物车页面（分别用 MyCatalog，MyCart widget 来展示）。虽然看上去是一个购物应用程序，但是你也可以和社交网络应用类比（把类别页面替换成朋友圈，把购物车替换成关注的人）。

The app has two separate screens: a catalog, and a cart (represented by the MyCatalog, and MyCart widgets, respectively). It could be a shopping app, but you can imagine the same structure in a simple social networking app (replace catalog for “wall” and cart for “favorites”).

类别页面包含一个自定义的 app bar (MyAppBar) 以及一个包含元素列表的可滑动的视图 (MyListItems)。

The catalog screen includes a custom app bar (MyAppBar) and a scrolling view of many list items (MyListItems).

这是应用程序对应的可视化的 widget 树。

Here’s the app visualized as a widget tree.

所以我们有至少 5 个 Widget 的子类。他们中有很多需要访问一些全局的状态。比如，MyListItem 会被添加到购物车中。但是它可能需要检查和自己相同的元素是否已经被添加到购物车中。

So we have at least 5 subclasses of Widget. Many of them need access to state that “belongs” elsewhere. For example, each MyListItem needs to be able to add itself to the cart. It might also want to see whether the currently displayed item is already in the cart.

这里我们出现了第一个问题：我们把当前购物车的状态放在哪合适呢？

This takes us to our first question: where should we put the current state of the cart?

提高状态的层级

Lifting state up

在 Flutter 中，有必要将存储状态的对象置于 widget 树中对应 widget 的上层。

In Flutter, it makes sense to keep the state above the widgets that use it.

为什么呢？在类似 Flutter 的声明式框架中，如果你想要修改 UI，那么你需要重构它。并没有类似 MyCart.updateWith(somethingNew) 的简单调用方法。换言之，你很难通过外部调用方法修改一个 widget。即便你自己实现了这样的模式，那也是和整个框架不相兼容。

Why? In declarative frameworks like Flutter, if you want to change the UI, you have to rebuild it. There is no easy way to have MyCart.updateWith(somethingNew). In other words, it’s hard to imperatively change a widget from outside, by calling a method on it. And even if you could make this work, you would be fighting the framework instead of letting it help you.

// BAD: DO NOT DO THIS
void myTapHandler() {
  var cartWidget = somehowGetMyCartWidget();
  cartWidget.updateWith(item);
}

即使你实现了上面的代码，也得处理 MyCart widget 中的代码：

Even if you get the above code to work, you would then have to deal with the following in the MyCart widget:

// BAD: DO NOT DO THIS
Widget build(BuildContext context) {
  return SomeWidget(
    // The initial state of the cart.
  );
}

void updateWith(Item item) {
  // Somehow you need to change the UI from here.
}

你可能需要考虑当前 UI 的状态，然后把最新的数据添加进去。但是这样的方式很难避免出现 bug。

You would need to take into consideration the current state of the UI and apply the new data to it. It’s hard to avoid bugs this way.

在 Flutter 中，每次当 widget 内容发生改变的时候，你就需要构造一个新的。你会调用 MyCart(contents)（构造函数），而不是 MyCart.updateWith(somethingNew)（调用方法）。因为你只能通过父类的 build 方法来构建新 widget，如果你想修改 contents，就需要调用 MyCart 的父类甚至更高一级的类。

In Flutter, you construct a new widget every time its contents change. Instead of MyCart.updateWith(somethingNew) (a method call) you use MyCart(contents) (a constructor). Because you can only construct new widgets in the build methods of their parents, if you want to change contents, it needs to live in MyCart’s parent or above.

// GOOD
void myTapHandler(BuildContext context) {
  var cartModel = somehowGetMyCartModel(context);
  cartModel.add(item);
}

这里 MyCart 可以在各种版本的 UI 中调用同一个代码路径。

Now MyCart has only one code path for building any version of the UI.

// GOOD
Widget build(BuildContext context) {
  var cartModel = somehowGetMyCartModel(context);
  return SomeWidget(
    // Just construct the UI once, using the current state of the cart.
    // ···
  );
}

在我们的例子中，contents会存在于 MyApp 的生命周期中。当它发生改变的时候，它会从上层重构 MyCart 。因为这个机制，所以 MyCart 无需考虑生命周期的问题—它只需要针对 contents 声明所需显示内容即可。当内容发生改变的时候，旧的 MyCart widget 就会消失，完全被新的 widget 替代。

In our example, contents needs to live in MyApp. Whenever it changes, it rebuilds MyCart from above (more on that later). Because of this, MyCart doesn’t need to worry about lifecycle—it just declares what to show for any given contents. When that changes, the old MyCart widget disappears and is completely replaced by the new one.

这就是我们所说的 widget 是不可变的。因为它们会直接被替换。

This is what we mean when we say that widgets are immutable. They don’t change—they get replaced.

现在我们知道在哪里放置购物车的状态，接下来看一下如何读取该状态。

Now that we know where to put the state of the cart, let’s see how to access it.

读取状态

Accessing the state

当用户点击类别页面中的一个元素，它会被添加到购物车里。然而当购物车在 widget 树中，处于 MyListItem 的层级之上时，又该如何访问状态呢？

When a user clicks on one of the items in the catalog, it’s added to the cart. But since the cart lives above MyListItem, how do we do that?

一个简单的实现方法是提供一个回调函数，当 MyListItem 被点击的时候可以调用。 Dart 的函数都是 first class 对象，所以你可以以任意方式传递它们。所以在 MyCatalog 里你可以使用下面的代码：

A simple option is to provide a callback that MyListItem can call when it is clicked. Dart’s functions are first class objects, so you can pass them around any way you want. So, inside MyCatalog you can define the following:

@override
Widget build(BuildContext context) {
  return SomeWidget(
    // Construct the widget, passing it a reference to the method above.
    MyListItem(myTapCallback),
  );
}

void myTapCallback(Item item) {
  print('user tapped on $item');
}

这段代码是没问题的，但是对于全局应用状态来说，你需要在不同的地方进行修改，可能需要大量传递回调函数——这些回调很快就会过时。

This works okay, but for an app state that you need to modify from many different places, you’d have to pass around a lot of callbacks—which gets old pretty quickly.

幸运的是 Flutter 在 widget 中存在一种机制，能够为其子孙节点提供数据和服务。（换言之，不仅仅是它的子节点，所有在它下层的 widget 都可以）。就像你所了解的， Flutter 中的 Everything is a Widget™。这里的机制也是一种 widget —InheritedWidget, InheritedNotifier, InheritedModel等等。我们这里不会详细解释他们，因为这些 widget 都太底层。

Fortunately, Flutter has mechanisms for widgets to provide data and services to their descendants (in other words, not just their children, but any widgets below them). As you would expect from Flutter, where Everything is a Widget™, these mechanisms are just special kinds of widgets—InheritedWidget, InheritedNotifier, InheritedModel, and more. We won’t be covering those here, because they are a bit low-level for what we’re trying to do.

我们会用一个 package 来和这些底层的 widget 打交道，就是 provider package。

Instead, we are going to use a package that works with the low-level widgets but is simple to use. It’s called provider.

在使用 provider 之前，请不要忘记在 pubspec.yaml 文件里加入依赖。

Before working with provider, don’t forget to add the dependency on it to your pubspec.yaml.

name: my_name
description: Blah blah blah.

# ...

dependencies:
  flutter:
    sdk: flutter

  provider: ^6.0.0

dev_dependencies:
  # ...

现在可以在代码里加入 import 'package:provider/provider.dart'; 进而开始构建你的应用了/

Now you can import 'package:provider/provider.dart'; and start building.

provider package 中，你无须关心回调或者 InheritedWidgets。但是你需要理解三个概念：

With provider, you don’t need to worry about callbacks or InheritedWidgets. But you do need to understand 3 concepts:

ChangeNotifier
ChangeNotifierProvider
Consumer

ChangeNotifier

ChangeNotifier 是 Flutter SDK 中的一个简单的类。它用于向监听器发送通知。换言之，如果被定义为 ChangeNotifier，你可以订阅它的状态变化。（这和大家所熟悉的观察者模式相类似）。

ChangeNotifier is a simple class included in the Flutter SDK which provides change notification to its listeners. In other words, if something is a ChangeNotifier, you can subscribe to its changes. (It is a form of Observable, for those familiar with the term.)

在 provider 中，ChangeNotifier 是一种能够封装应用程序状态的方法。对于特别简单的程序，你可以通过一个 ChangeNotifier 来满足全部需求。在相对复杂的应用中，由于会有多个模型，所以可能会有多个 ChangeNotifier。 (不是必须得把 ChangeNotifier 和 provider 结合起来用，不过它确实是一个特别简单的类)。

In provider, ChangeNotifier is one way to encapsulate your application state. For very simple apps, you get by with a single ChangeNotifier. In complex ones, you’ll have several models, and therefore several ChangeNotifiers. (You don’t need to use ChangeNotifier with provider at all, but it’s an easy class to work with.)

在我们的购物应用示例中，我们打算用 ChangeNotifier 来管理购物车的状态。我们创建一个新类，继承它，像下面这样：

In our shopping app example, we want to manage the state of the cart in a ChangeNotifier. We create a new class that extends it, like so:

class CartModel extends ChangeNotifier {
  /// Internal, private state of the cart.
  final List<Item> _items = [];

  /// An unmodifiable view of the items in the cart.
  UnmodifiableListView<Item> get items => UnmodifiableListView(_items);

  /// The current total price of all items (assuming all items cost $42).
  int get totalPrice => _items.length * 42;

  /// Adds [item] to cart. This and [removeAll] are the only ways to modify the
  /// cart from the outside.
  void add(Item item) {
    _items.add(item);
    // This call tells the widgets that are listening to this model to rebuild.
    notifyListeners();
  }

  /// Removes all items from the cart.
  void removeAll() {
    _items.clear();
    // This call tells the widgets that are listening to this model to rebuild.
    notifyListeners();
  }
}

唯一一行和 ChangeNotifier 相关的代码就是调用 notifyListeners()。当模型发生改变并且需要更新 UI 的时候可以调用该方法。而剩下的代码就是 CartModel 和它本身的业务逻辑。

The only code that is specific to ChangeNotifier is the call to notifyListeners(). Call this method any time the model changes in a way that might change your app’s UI. Everything else in CartModel is the model itself and its business logic.

ChangeNotifier 是 flutter:foundation 的一部分，而且不依赖 Flutter 中任何高级别类。测试起来非常简单（你都不需要使用 widget 测试）。比如，这里有一个针对 CartModel 简单的单元测试：

ChangeNotifier is part of flutter:foundation and doesn’t depend on any higher-level classes in Flutter. It’s easily testable (you don’t even need to use widget testing for it). For example, here’s a simple unit test of CartModel:

test('adding item increases total cost', () {
  final cart = CartModel();
  final startingPrice = cart.totalPrice;
  cart.addListener(() {
    expect(cart.totalPrice, greaterThan(startingPrice));
  });
  cart.add(Item('Dash'));
});

ChangeNotifierProvider

ChangeNotifierProvider widget 可以向其子孙节点暴露一个 ChangeNotifier 实例。它属于 provider package。

ChangeNotifierProvider is the widget that provides an instance of a ChangeNotifier to its descendants. It comes from the provider package.

我们已经知道了该把 ChangeNotifierProvider 放在什么位置：在需要访问它的 widget 之上。在 CartModel 里，也就意味着将它置于 MyCart 和 MyCatalog 之上。

We already know where to put ChangeNotifierProvider: above the widgets that need to access it. In the case of CartModel, that means somewhere above both MyCart and MyCatalog.

你肯定不愿意把 ChangeNotifierProvider 放的级别太高（因为你不希望破坏整个结构）。但是在我们这里的例子中，MyCart 和 MyCatalog 之上只有 MyApp。

You don’t want to place ChangeNotifierProvider higher than necessary (because you don’t want to pollute the scope). But in our case, the only widget that is on top of both MyCart and MyCatalog is MyApp.

void main() {
  runApp(
    ChangeNotifierProvider(
      create: (context) => CartModel(),
      child: const MyApp(),
    ),
  );
}

请注意我们定义了一个 builder 来创建一个 CartModel 的实例。 ChangeNotifierProvider 非常聪明，它不会重复实例化 CartModel，除非在个别场景下。如果该实例已经不会再被调用， ChangeNotifierProvider 也会自动调用 CartModel 的 dispose() 方法。

Note that we’re defining a builder that creates a new instance of CartModel. ChangeNotifierProvider is smart enough not to rebuild CartModel unless absolutely necessary. It also automatically calls dispose() on CartModel when the instance is no longer needed.

如果你想提供更多状态，可以使用 MultiProvider：

If you want to provide more than one class, you can use MultiProvider:

void main() {
  runApp(
    MultiProvider(
      providers: [
        ChangeNotifierProvider(create: (context) => CartModel()),
        Provider(create: (context) => SomeOtherClass()),
      ],
      child: const MyApp(),
    ),
  );
}

Consumer

现在 CartModel 已经通过 ChangeNotifierProvider 在应用中与 widget 相关联。我们可以开始调用它了。

Now that CartModel is provided to widgets in our app through the ChangeNotifierProvider declaration at the top, we can start using it.

完成这一步需要通过 Consumer widget。

This is done through the Consumer widget.

return Consumer<CartModel>(
  builder: (context, cart, child) {
    return Text("Total price: ${cart.totalPrice}");
  },
);

我们必须指定要访问的模型类型。在这个示例中，我们要访问 CartModel 那么就写上 Consumer<CartModel>。

We must specify the type of the model that we want to access. In this case, we want CartModel, so we write Consumer<CartModel>. If you don’t specify the generic (<CartModel>), the provider package won’t be able to help you. provider is based on types, and without the type, it doesn’t know what you want.

Consumer widget 唯一必须的参数就是 builder。当 ChangeNotifier 发生变化的时候会调用 builder 这个函数。（换言之，当你在模型中调用 notifyListeners() 时，所有相关的 Consumer widget 的 builder 方法都会被调用。）

The only required argument of the Consumer widget is the builder. Builder is a function that is called whenever the ChangeNotifier changes. (In other words, when you call notifyListeners() in your model, all the builder methods of all the corresponding Consumer widgets are called.)

builder 在被调用的时候会用到三个参数。第一个是 context。在每个 build 方法中都能找到这个参数。

The builder is called with three arguments. The first one is context, which you also get in every build method.

builder 函数的第二个参数是 ChangeNotifier 的实例。它是我们最开始就能得到的实例。你可以通过该实例定义 UI 的内容。

The second argument of the builder function is the instance of the ChangeNotifier. It’s what we were asking for in the first place. You can use the data in the model to define what the UI should look like at any given point.

第三个参数是 child，用于优化目的。如果 Consumer 下面有一个庞大的子树，当模型发生改变的时候，该子树 并不会 改变，那么你就可以仅仅创建它一次，然后通过 builder 获得该实例。

The third argument is child, which is there for optimization. If you have a large widget subtree under your Consumer that doesn’t change when the model changes, you can construct it once and get it through the builder.

return Consumer<CartModel>(
  builder: (context, cart, child) => Stack(
    children: [
      // Use SomeExpensiveWidget here, without rebuilding every time.
      if (child != null) child,
      Text("Total price: ${cart.totalPrice}"),
    ],
  ),
  // Build the expensive widget here.
  child: const SomeExpensiveWidget(),
);

最好能把 Consumer 放在 widget 树尽量低的位置上。你总不希望 UI 上任何一点小变化就全盘重新构建 widget 吧。

It is best practice to put your Consumer widgets as deep in the tree as possible. You don’t want to rebuild large portions of the UI just because some detail somewhere changed.

// DON'T DO THIS
return Consumer<CartModel>(
  builder: (context, cart, child) {
    return HumongousWidget(
      // ...
      child: AnotherMonstrousWidget(
        // ...
        child: Text('Total price: ${cart.totalPrice}'),
      ),
    );
  },
);

换成：

Instead:

// DO THIS
return HumongousWidget(
  // ...
  child: AnotherMonstrousWidget(
    // ...
    child: Consumer<CartModel>(
      builder: (context, cart, child) {
        return Text('Total price: ${cart.totalPrice}');
      },
    ),
  ),
);

Provider.of

有的时候你不需要模型中的数据来改变 UI，但是你可能还是需要访问该数据。比如，ClearCart 按钮能够清空购物车的所有商品。它不需要显示购物车里的内容，只需要调用 clear() 方法。

Sometimes, you don’t really need the data in the model to change the UI but you still need to access it. For example, a ClearCart button wants to allow the user to remove everything from the cart. It doesn’t need to display the contents of the cart, it just needs to call the clear() method.

我们可以使用 Consumer<CartModel> 来实现这个效果，不过这么实现有点浪费。因为我们让整体框架重构了一个无需重构的 widget。

We could use Consumer<CartModel> for this, but that would be wasteful. We’d be asking the framework to rebuild a widget that doesn’t need to be rebuilt.

所以这里我们可以使用 Provider.of，并且将 listen 设置为 false。

For this use case, we can use Provider.of, with the listen parameter set to false.

Provider.of<CartModel>(context, listen: false).removeAll();

在 build 方法中使用上面的代码，当 notifyListeners 被调用的时候，并不会使 widget 被重构。

Using the above line in a build method won’t cause this widget to rebuild when notifyListeners is called.

把代码集成在一起

Putting it all together

你可以在文章中查看这个示例。如果你想参考稍微简单一点的示例，可以看看 Counter 应用程序是如何基于 provider 实现的。

You can check out the example covered in this article. If you want something simpler, see what the simple Counter app looks like when built with provider.

通过跟着这些文章的学习，你已经大大提高了创建一个包含状态管理应用的能力。试着自己用 provider 构建一个应用来掌握这些技能吧！

By following along with these articles, you’ve greatly improved your ability to create state-based applications. Try building an application with provider yourself to master these skills.

状态 (State) 管理参考

总体概览
General overview
Provider
Riverpod
setState
InheritedWidget & InheritedModel
Redux
Fish-Redux
BLoC / Rx
GetIt
MobX
Flutter Commands
Binder
GetX
states_rebuilder
Triple Pattern (Segmented State Pattern)

状态管理是一个相当复杂的话题。如果您在浏览后发现一些问题并未得到解答，或者并不适用于您的具体需求场景，自信些，您的实现就是对的。

State management is a complex topic. If you feel that some of your questions haven’t been answered, or that the approach described on these pages is not viable for your use cases, you are probably right.

通过下面的链接了解更多的信息，其中有很多信息都是由社区（第三方）提供。

Learn more at the following links, many of which have been contributed by the Flutter community:

总体概览

General overview

在选择一个具体内容前，您可以先查看以下几项。

Things to review before selecting an approach.

状态管理的介绍。这是本篇内容的总起。（当您直接跳转到了该页面，但错过了其他页面时，可以先从这里开始阅读）
Introduction to state management, which is the beginning of this very section (for those of you who arrived directly to this Options page and missed the previous pages)
Flutter 实用状态管理 (Pragmatic State Management in Flutter)，来自 Google I/O 2019 的介绍视频。
Pragmatic State Management in Flutter, a video from Google I/O 2019
Flutter 架构实例 (Flutter Architecture Samples)， Brian Egan 著。
Flutter Architecture Samples, by Brian Egan

Provider

推荐的管理方式。

A recommended approach.

简易的应用状态管理 (Simple app state management)，这是本节内容的上篇。
Simple app state management, the previous page in this section
Provider 依赖包 (Provider package)
Provider package
你可能并不需要 Redux：Flutter 专版 (You might not need Redux: The Flutter edition)
You might not need Redux: The Flutter edition, by Ryan Edge
学习并理解 Flutter Providers (Making sense of all those Flutter Providers)
Making sense of all those Flutter Providers

Riverpod

Riverpod 是另一个不错的选择，它类似于 Provider，并且是编译安全和可测试的。 Riverpod 不依赖于 Flutter SDK。

Riverpod, another good choice, is similar to Provider and is compile-safe and testable. Riverpod doesn’t have a dependency on the Flutter SDK.

Riverpod homepage
Getting started with Riverpod

setState

适用于较小规模 widget 的暂时性状态的基础管理方法。

The low-level approach to use for widget-specific, ephemeral state.

为你的 Flutter 应用添加交互 (Adding interactivity to your Flutter app)，一篇 Flutter 的教程。
Adding interactivity to your Flutter app, a Flutter tutorial
Flutter 中的基础状态管理 (Basic state management in Google Flutter)，Agung Surya 著。
Basic state management in Google Flutter, by Agung Surya

InheritedWidget & InheritedModel

Widget tree 中不同层级间的 widget 通信的基础方法。这是诸如 provider 等众多方法的底层实现。

The low-level approach used to communicate between ancestors and children in the widget tree. This is what provider and many other approaches use under the hood.

以下讲师指导的视频 workshop 介绍了如何使用 InheritedWidget：

The following instructor-led video workshop covers how to use InheritedWidget:

其他有用的文档包括：

Other useful docs include:

InheritedWidget 文档 (InheritedWidget docs)
InheritedWidget docs
使用 InheritedWidgets 管理 Flutter 应用状态 (Managing Flutter Application State With InheritedWidgets)， Hans Muller 著。
Managing Flutter Application State With InheritedWidgets, by Hans Muller
继承 Widgets (Inheriting Widgets)， Mehmet Fidanboyly 著。
Inheriting Widgets, by Mehmet Fidanboylu
高效地使用 Flutter 继承 Widgets (Using Flutter Inherited Widgets Effectively)，Eric Windmill 著。
Using Flutter Inherited Widgets Effectively, by Eric Windmill
Widget - State - Context - InheritedWidget，Didier Bolelens 著。
Widget - State - Context - InheritedWidget, by Didier Bolelens

Redux

前端开发者较为熟悉的状态容器实现。

A state container approach familiar to many web developers.

使用 Redux 在 Flutter 中管理动画 (Animation Management with Redux and Flutter)，来自 DartConf 2018 的视频，以及 Medium 的配套文章 (Accompanying article on Medium)。
Animation Management with Redux and Flutter, a video from DartConf 2018 Accompanying article on Medium
Flutter Redux 依赖包
Flutter Redux package
Dart 与 Flutter 中的 Redux 中间件 Saga，Bilal Uslu 著
Redux Saga Middleware Dart and Flutter, by Bilal Uslu
Flutter 中的 Redux 介绍， Xavi Rigau 著。
Introduction to Redux in Flutter, by Xavi Rigau
Flutter + Redux—构建一个购物列表 APP (Flutter + Redux—How to make a shopping list app)，发布于 Hackernoon，Paulina Szklarska 著。
Flutter + Redux—How to make a shopping list app, by Paulina Szklarska on Hackernoon
用 Flutter Redux 构建一个任务应用 (CRUD) —第一部分 (Building a TODO application (CRUD) in Flutter with Redux—Part 1)，由 Tensor Programming 制作的视频。
Building a TODO application (CRUD) in Flutter with Redux—Part 1, a video by Tensor Programming
Flutter Redux Thunk 示例 (Flutter Redux Thunk, an example)，Jack Wong 著。
Flutter Redux Thunk, an example, by Jack Wong
使用 Redux 构建（大型）Flutter 应用 (Building a (large) Flutter app with Redux)，Hillel Coren 著。
Building a (large) Flutter app with Redux, by Hillel Coren
Fish-Redux—基于 Redux 封装的 Flutter 应用框架 (Fish-Redux–An assembled flutter application framework based on Redux)，阿里巴巴著。
Fish-Redux–An assembled flutter application framework based on Redux, by Alibaba
异步 Redux—没有模板的 Redux，允许同步和异步 reducers (Async Redux–Redux without boilerplate. Allows for both sync and async reducers)，Marcelo Glasberg 著。
Async Redux–Redux without boilerplate. Allows for both sync and async reducers, by Marcelo Glasberg
当 Flutter 遇见 Redux：以 Redux 的风格管理 Flutter 应用的状态 (Flutter meets Redux: The Redux way of managing Flutter applications state)，Amir Ghezelbash 著。
Flutter meets Redux: The Redux way of managing Flutter applications state, by Amir Ghezelbash
使用 Redux 更好地组织 Flutter 应用的代码以管理项目目标 (Redux and epics for better-organized code in Flutter apps)，Nihad Delic 著。
Redux and epics for better-organized code in Flutter apps, by Nihad Delic

Fish-Redux

Fish Redux 是一个基于 Redux 状态管理的组合式 Flutter 应用框架，适用于构建中型和大型应用。

Fish Redux is an assembled flutter application framework based on Redux state management. It is suitable for building medium and large applications.

由阿里巴巴开发的 Fish-Redux-Library package
Fish-Redux-Library package, by Alibaba
Fish-Redux-Source，工程代码
Fish-Redux-Source, project code
Flutter-Movie 展示如何使用 Fish Redux 的简单示例应用，包含 30 多个页面、graphql、支付 api 和媒体播放器等。
Flutter-Movie, A non-trivial example demonstrating how to use Fish Redux, with more than 30 screens, graphql, payment api, and media player.

BLoC / Rx

基于流/观察者模式的系列。

A family of stream/observable based patterns.

使用 BLoC 模式构建你的 Flutter 项目 (Architect your Flutter project using BLoC pattern)， Sagar Suri 著。
Architect your Flutter project using BLoC pattern, by Sagar Suri
BLoC 库 (BLoC Library)，Felix Angelov 著。
BloC Library, by Felix Angelov
响应式编程 - 流 - BLoC - 用例 (Reactive Programming - Streams - BLoC - Practical Use Cases)， Didier Boelens 著。
Reactive Programming - Streams - BLoC - Practical Use Cases, by Didier Boelens

GetIt

A service locator based state management approach that doesn’t need a BuildContext.

GetIt package, the service locator. It can also be used together with BloCs.
GetIt Mixin package, a mixin that completes GetIt to a full state management solution.
GetIt Hooks package, same as the mixin in case you already use flutter_hooks.
Flutter state management for minimalists, by Suragch

MobX

一个基于观察及响应的状态管理常用库。

A popular library based on observables and reactions.

Flutter Commands

基于 ValueNotifiers 的命令式的状态管理，能与 GetIt 完美结合使用，也可以与 Provider 或者其他 locators 配合使用。

Reactive state management that uses the Command Pattern and is based on ValueNotifiers. Best in combination with GetIt, but can be used with Provider or other locators too.

Flutter Command package
RxCommand package, 基于 Stream 的实现.

Binder

一个使用 InheritedWidget 作为核心实现的状态管理库。受到 recoil 的启发，该库提供了分治的解决方式。

A state management package that uses InheritedWidget at its core. Inspired in part by recoil. This package promotes the separation of concerns.

Binder 包
Binder package
Binder 样例
Binder examples
Binder snippets 是一个 vscode 插件，能够将代码拆分以获得更高的生产力
Binder snippets, vscode snippets to be even more productive with Binder

GetX

一个简单的响应式状态管理解决方案。

A simplified reactive state management solution.

GetX package
Complete GetX State Management, a video by Tadas Petra
GetX Flutter Firebase Auth Example, by Jeff McMorris

states_rebuilder

一种将状态管理与依赖注入解决方案和集成路由器相结合的方法。更多信息，请参阅以下信息：

An approach that combines state management with a dependency injection solution and an integrated router. For more information, see the following info:

States Rebuilder 项目代码
States Rebuilder project code
States Rebuilder documentation

Triple Pattern (Segmented State Pattern)

Triple is a pattern for state management that uses Streams or ValueNotifier. This mechanism (nicknamed triple because the stream always uses three values: Error, Loading, and State), is based on the Segmented State pattern.

For more information, refer to the following resources:

Triple documentation
Flutter Triple package
Triple Pattern: A new pattern for state management in Flutter (blog post written in Portuguese but can be auto-translated)
VIDEO: Flutter Triple Pattern by Kevlin Ossada (recorded in English)

网络

Cross-platform http networking
Platform notes
- Android
Samples

Cross-platform http networking

The http package provides the simplest way to issue http requests. This package is supported on Android, iOS, and the web.

Platform notes

Some platforms require additional steps, as detailed below.

Android

Android apps must declare their use of the internet in the Android manifest (AndroidManifest.xml ):

<manifest xmlns:android...>
 ...
 <uses-permission android:name="android.permission.INTERNET" />
 <application ...
</manifest>

Samples

For a practical sample of various networking tasks (incl. fetching data, WebSockets, and parsing data in the background) see the networking cookbook.

JSON 和序列化数据

我需要哪一种 JSON 序列化数据方法？
Which JSON serialization method is right for me?
- 为较小的项目使用手动序列化数据
  Use manual serialization for smaller projects
- 为中大型项目使用代码生成
  Use code generation for medium to large projects
Flutter 中是否有 GSON/Jackson/Moshi 的等价物？
Is there a GSON/Jackson/Moshi equivalent in Flutter?
使用 dart:convert 手动序列化 JSON 数据
Serializing JSON manually using dart:convert
- 内联序列化 JSON 数据
  Serializing JSON inline
- 在模型类中序列化 JSON 数据
  Serializing JSON inside model classes
使用代码生成库序列化 JSON 数据
Serializing JSON using code generation libraries
为嵌套类 (Nested Classes) 生成代码
Generating code for nested classes
进一步参考
Further references

大多数移动应用都需要与 web 服务器通信，同时在某些时候轻松地存储结构化数据。当创造需要网络连接的应用时，它迟早需要处理一些常见的 JSON。

It is hard to think of a mobile app that doesn’t need to communicate with a web server or easily store structured data at some point. When making network-connected apps, the chances are that it needs to consume some good old JSON, sooner or later.

本指南介绍了如何在 Flutter 中使用 JSON。包括了如何在不同场景中使用相应的 JSON 解决方案，以及为什么要这么做。

This guide looks into ways of using JSON with Flutter. It covers which JSON solution to use in different scenarios, and why.

术语： 编码和 序列化数据 是一回事——将数据结构转换为字符串。解码和 反序列化数据 则是相反的过程——将字符串转换为数据结构。然而，序列化数据 通常也指代将数据结构转换为更加易读的数据格式的整个过程。

Terminology: Encoding and serialization are the same thing—turning a data structure into a string. Decoding and deserialization are the opposite process—turning a string into a data structure. However, serialization also commonly refers to the entire process of translating data structures to and from a more easily readable format.

为了避免混淆，本文档在涉及到整个过程时将使用“序列化数据”，在特指其中某个过程时使用“编码”和“解码”。

To avoid confusion, this doc uses “serialization” when referring to the overall process, and “encoding” and “decoding” when specifically referring to those processes.

我需要哪一种 JSON 序列化数据方法？

Which JSON serialization method is right for me?

本文涵盖了两种常规的 JSON 使用策略：

This article covers two general strategies for working with JSON:

手动序列化数据
Manual serialization
利用代码生成进行自动序列化数据
Automated serialization using code generation

不同的项目复杂度不同，用例也不一样。对于较小的概念验证项目或者快速原型，使用代码生成器可能有些过于繁杂。对于具有很多更加复杂的 JSON 模型的应用，手动编码可能很快变得无聊、重复并且出现很多小错误。

Different projects come with different complexities and use cases. For smaller proof-of-concept projects or quick prototypes, using code generators might be overkill. For apps with several JSON models with more complexity, encoding by hand can quickly become tedious, repetitive, and lend itself to many small errors.

为较小的项目使用手动序列化数据

Use manual serialization for smaller projects

手动 JSON 解码是指在 dart:convert 中使用内置的 JSON 解码器。它包括将原始 JSON 字符串传递给 jsonDecode() 方法，然后在产生的 Map<String, dynamic> 计算结果中寻找你需要的值。它没有外部依赖或者特定的设置过程，这有利于快速证明概念。

Manual JSON decoding refers to using the built-in JSON decoder in dart:convert. It involves passing the raw JSON string to the jsonDecode() function, and then looking up the values you need in the resulting Map<String, dynamic>. It has no external dependencies or particular setup process, and it’s good for a quick proof of concept.

当你的项目变大时，手动解码表现得并不理想。手动编写解码逻辑会变得难以管理并容易出错。如果你产生了笔误去获取一个不存在的 JSON 字段，你的代码会在运行时抛出一个错误。

Manual decoding does not perform well when your project becomes bigger. Writing decoding logic by hand can become hard to manage and error-prone. If you have a typo when accessing a nonexistent JSON field, your code throws an error during runtime.

如果你的项目没有很多的 JSON 模型并且你正在寻找一个快速测试概念的方法，手动序列化数据可能是你要的开始的方式。关于手动编码的示例，请参阅使用 dart:convert 手动序列化 JSON 数据。

If you do not have many JSON models in your project and are looking to test a concept quickly, manual serialization might be the way you want to start. For an example of manual encoding, see Serializing JSON manually using dart:convert.

为中大型项目使用代码生成

Use code generation for medium to large projects

利用代码生成的 JSON 序列化数据，意味着可以通过外部的库生成编码模板。在一些初始化设置后，你可以运行文件监听程序，来从你的模型类生成代码。例如，json_serializable 和 built_value 就是这类的库。

JSON serialization with code generation means having an external library generate the encoding boilerplate for you. After some initial setup, you run a file watcher that generates the code from your model classes. For example, json_serializable and built_value are these kinds of libraries.

这种方法适用于大型项目。不需要手动编写模板，并且一些试图去获取不存在的 JSON 字段的笔误，会在编译阶段被发现。代码生成的麻烦之处，在于它需要一些初始化设置。并且，生成的源文件可能在你的项目导航中产生一些视觉上的混乱。

This approach scales well for a larger project. No hand-written boilerplate is needed, and typos when accessing JSON fields are caught at compile-time. The downside with code generation is that it requires some initial setup. Also, the generated source files might produce visual clutter in your project navigator.

当你有一个中大型项目时，你可能想要使用生成的代码来进行 JSON 序列化。要看基于代码生成的 JSON 编码，见使用代码生成库序列化 JSON 数据。

You might want to use generated code for JSON serialization when you have a medium or a larger project. To see an example of code generation based JSON encoding, see Serializing JSON using code generation libraries.

Flutter 中是否有 GSON/Jackson/Moshi 的等价物？

Is there a GSON/Jackson/Moshi equivalent in Flutter?

简单来说，没有。

The simple answer is no.

这样的库需要使用运行时进行反射，这在 Flutter 中是被禁用的。运行时反射会影响 Dart 支持了相当久的摇树优化。通过 tree shaking，你可以从你的发布版本中“抖掉”不需要使用的代码。这会显著优化 App 的体积。

Such a library would require using runtime reflection, which is disabled in Flutter. Runtime reflection interferes with tree shaking, which Dart has supported for quite a long time. With tree shaking, you can “shake off” unused code from your release builds. This optimizes the app’s size significantly.

由于反射会默认让所有的代码被隐式使用，这让 tree shaking 变得困难。工具不知道哪一部分在运行时不会被用到，所以冗余的代码很难被清除。当使用反射时，App 的体积不能被轻易优化。

Since reflection makes all code implicitly used by default, it makes tree shaking difficult. The tools cannot know what parts are unused at runtime, so the redundant code is hard to strip away. App sizes cannot be easily optimized when using reflection.

尽管你不能在 Flutter 中使用运行时反射，还是有一些库提供了基于代码生成的方便使用的 API，这个方法的更多细节在代码生成库部分。

Although you cannot use runtime reflection with Flutter, some libraries give you similarly easy-to-use APIs but are based on code generation instead. This approach is covered in more detail in the code generation libraries section.

使用 dart:convert 手动序列化 JSON 数据

Serializing JSON manually using dart:convert

在 Flutter 中基础的序列化 JSON 十分容易的。 Flutter 有一个内置的 dart:convert 的库，这个库包含了一个简单的 JSON 编码器和解码器。

Basic JSON serialization in Flutter is very simple. Flutter has a built-in dart:convert library that includes a straightforward JSON encoder and decoder.

下面的样例实现了一个简单用户模型。

The following sample JSON implements a simple user model.

{
  "name": "John Smith",
  "email": "john@example.com"
}

通过 dart:convert，你可以用两种方法编码这个 JSON 模型。

With dart:convert, you can serialize this JSON model in two ways.

内联序列化 JSON 数据

Serializing JSON inline

通过查阅 dart:convert 文档，你会看到你可以将 JSON 字符串作为方法的参数，调用 jsonDecode() 方法来解码 JSON。

By looking at the dart:convert documentation, you’ll see that you can decode the JSON by calling the jsonDecode() function, with the JSON string as the method argument.

Map<String, dynamic> user = jsonDecode(jsonString);

print('Howdy, ${user['name']}!');
print('We sent the verification link to ${user['email']}.');

不幸的是，jsonDecode() 返回一个 Map<String, dynamic>，这意味着你在运行时以前都不知道值的类型。使用这个方法，你失去了大部分的静态类型语言特性：类型安全、自动补全以及最重要的编译时异常。你的代码会立即变得更加容易出错。

Unfortunately, jsonDecode() returns a Map<String, dynamic>, meaning that you do not know the types of the values until runtime. With this approach, you lose most of the statically typed language features: type safety, autocompletion and most importantly, compile-time exceptions. Your code will become instantly more error-prone.

例如，当你获取 name 或者 email 字段，你可能很快引入一个笔误。然而编译器却无法知道映射中是否有 JSON 笔误。

For example, whenever you access the name or email fields, you could quickly introduce a typo. A typo that the compiler doesn’t know about since the JSON lives in a map structure.

在模型类中序列化 JSON 数据

Serializing JSON inside model classes

通过引入一个简单的模型 User 类来解决上面提到的问题。在 User 类中，你会发现：

Combat the previously mentioned problems by introducing a plain model class, called User in this example. Inside the User class, you’ll find:

一个 User.fromJson() 构造函数，用于从映射中构造一个新的 User 实例。
A User.fromJson() constructor, for constructing a new User instance from a map structure.
一个 toJson() 方法，这个方法会将 User 实例转换为一个映射。
A toJson() method, which converts a User instance into a map.

通过这种方法，调用代码 可以拥有类型安全、 name 和 email 字段的自动完成以及编译时异常检测。如果你不小心写错了，或者把 String 类型的字段看成了 int 类型，应用将无法编译，而不是在运行时崩溃。

With this approach, the calling code can have type safety, autocompletion for the name and email fields, and compile-time exceptions. If you make typos or treat the fields as ints instead of Strings, the app won’t compile, instead of crashing at runtime.

user.dart

class User {
  final String name;
  final String email;

  User(this.name, this.email);

  User.fromJson(Map<String, dynamic> json)
      : name = json['name'],
        email = json['email'];

  Map<String, dynamic> toJson() => {
        'name': name,
        'email': email,
      };
}

解码逻辑的责任现在转移到了模型内部。通过这个新方法，你可以很容易地解码获得一个 user 实例。

The responsibility of the decoding logic is now moved inside the model itself. With this new approach, you can decode a user easily.

Map<String, dynamic> userMap = jsonDecode(jsonString);
var user = User.fromJson(userMap);

print('Howdy, ${user.name}!');
print('We sent the verification link to ${user.email}.');

要对 user 实例进行编码，将 User 对象传到 jsonEncode() 函数中。你不需要调用 toJson() 方法，因为 jsonEncode() 已经帮你做了这件事。

To encode a user, pass the User object to the jsonEncode() function. You don’t need to call the toJson() method, since jsonEncode() already does it for you.

String json = jsonEncode(user);

通过这种方法，被调用的代码根本不需要担心序列化 JSON 数据的问题。然而，你仍然需要模型类。你当然会希望序列化数据在一个生产环境的应用里能奏效。在实践中，User.fromJson() 和 User.toJson() 方法都需要单元测试以便验证正确的行为。

With this approach, the calling code doesn’t have to worry about JSON serialization at all. However, the model class still definitely has to. In a production app, you would want to ensure that the serialization works properly. In practice, the User.fromJson() and User.toJson() methods both need to have unit tests in place to verify correct behavior.

然而，现实场景通常不是那么简单，有时候响应的 JSON API 会更加复杂，例如它可能会包含一些相邻的 JSON 对象，而这些对象同样需要使用它的 model 类进行解析。

However, real-world scenarios are not usually that simple. Sometimes JSON API responses are more complex, for example since they contain nested JSON objects that must be parsed through their own model class.

如果有一些东西可以帮你处理 JSON 编码和解码就好了。幸运的是，已经有了！

It would be nice if there were something that handled the JSON encoding and decoding for you. Luckily, there is!

使用代码生成库序列化 JSON 数据

Serializing JSON using code generation libraries

尽管有其它库可以使用，但是本指南使用了 json_serializable，一个自动化源代码生成器来为你生成 JSON 序列化数据模板。

Although there are other libraries available, this guide uses json_serializable, an automated source code generator that generates the JSON serialization boilerplate for you.

选择一个 library 你也许已经发现了，在 pub.dev 上有两个用于生成 JSON 序列化代码的 Flutter Favorite package， json_serializable 以及 built_value。那么你该如何在它们之间进行选择呢？ json_serializable package 能够通过注解让你的普通类序列化，而 built_value package 则提供了更高层次的方法，让定义为无变化的类也能够被序列化为 JSON。

Choosing a library: You might have noticed two Flutter Favorite packages on pub.dev that generate JSON serialization code, json_serializable and built_value. How do you choose between these packages? The json_serializable package allows you to make regular classes serializable by using annotations, whereas the built_value package provides a higher-level way of defining immutable value classes that can also be serialized to JSON.

由于序列化数据代码不再需要手动编写或者维护，你可以将序列化 JSON 数据在运行时的异常风险降到最低。

Since the serialization code is not handwritten or maintained manually anymore, you minimize the risk of having JSON serialization exceptions at runtime.

在项目中设置 json_serializable

Setting up json_serializable in a project

要在你的项目中包含 json_serializable，你需要一个常规依赖，以及两个 dev 依赖。简单来说，dev 依赖 是不包括在我们的 App 源代码中的依赖——它们只会被用在开发环境中。

To include json_serializable in your project, you need one regular dependency, and two dev dependencies. In short, dev dependencies are dependencies that are not included in our app source code—they are only used in the development environment.

在序列化 JSON 数据的例子中，这些需要的依赖的最新版本可以在 pubspec 文件中查看。

The latest versions of these required dependencies can be seen by following the pubspec file in the JSON serializable example.

pubspec.yaml

dependencies:
  # Your other regular dependencies here
  json_annotation: <latest_version>

dev_dependencies:
  # Your other dev_dependencies here
  build_runner: <latest_version>
  json_serializable: <latest_version>

在你的项目根文件夹下运行 flutter pub get （或者在你的编辑器中点击 Packages Get）以确保在你的项目中可以使用这些新的依赖。

Run flutter pub get inside your project root folder (or click Packages get in your editor) to make these new dependencies available in your project.

以 json_serializable 的方式创建模型类

Creating model classes the json_serializable way

下面显示了怎样将 User 类转换为 json_serializable 后的类。简单起见，该代码使用了前面的例子中的简化的 JSON 模型。

The following shows how to convert the User class to a json_serializable class. For the sake of simplicity, this code uses the simplified JSON model from the previous samples.

user.dart

import 'package:json_annotation/json_annotation.dart';

/// This allows the `User` class to access private members in
/// the generated file. The value for this is *.g.dart, where
/// the star denotes the source file name.
part 'user.g.dart';

/// An annotation for the code generator to know that this class needs the
/// JSON serialization logic to be generated.
@JsonSerializable()
class User {
  User(this.name, this.email);

  String name;
  String email;

  /// A necessary factory constructor for creating a new User instance
  /// from a map. Pass the map to the generated `_$UserFromJson()` constructor.
  /// The constructor is named after the source class, in this case, User.
  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);

  /// `toJson` is the convention for a class to declare support for serialization
  /// to JSON. The implementation simply calls the private, generated
  /// helper method `_$UserToJson`.
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

通过这个设置，源代码生成器将生成用于 JSON 编码及解码 name 以及 email 字段的代码。

With this setup, the source code generator generates code for encoding and decoding the name and email fields from JSON.

如果需要，你可以很轻易地自定义命名策略。例如，如果 API 返回带有 蛇形命名方式 的对象，并且你想要在你的模型里使用 小驼峰 的命名方式，你可以使用带有一个 name 参数的 @JsonKey 注解。

If needed, it is also easy to customize the naming strategy. For example, if the API returns objects with snake_case, and you want to use lowerCamelCase in your models, you can use the @JsonKey annotation with a name parameter:

/// Tell json_serializable that "registration_date_millis" should be
/// mapped to this property.
@JsonKey(name: 'registration_date_millis')
final int registrationDateMillis;

客户端和服务端最好保持同样的命名规则。 @JsonSerializable() 提供了 fieldRename 枚举，用于将 dart 字段完整转换为 JSON 键值。

It’s best if both server and client follow the same naming strategy.
@JsonSerializable() provides fieldRename enum for totally converting dart fields into JSON keys.

定义 @JsonSerializable(fieldRename: FieldRename.snake) 与添加 @JsonKey(name: '<snake_case>') 到每一个字段是同样的效果。

Modifying @JsonSerializable(fieldRename: FieldRename.snake) is equivalent to adding @JsonKey(name: '<snake_case>') to each field.

服务端的数据有时无法确认，所以在客户端很有必要进行数据校验和保护。其他常见的 @JsonKey 声明方法包括：

Sometimes server data is uncertain, so it is necessary to verify and protect data on client.
Other commonly used @JsonKey annotations include:

/// Tell json_serializable to use "defaultValue" if the JSON doesn't
/// contain this key or if the value is `null`.
@JsonKey(defaultValue: false)
final bool isAdult;

/// When `true` tell json_serializable that JSON must contain the key, 
/// If the key doesn't exist, an exception is thrown.
@JsonKey(required: true)
final String id;

/// When `true` tell json_serializable that generated code should 
/// ignore this field completely. 
@JsonKey(ignore: true)
final String verificationCode;

运行代码生成工具

Running the code generation utility

当你首次创建 json_serializable 类时，你会得到类似下图的错误。

When creating json_serializable classes the first time, you’ll get errors similar to what is shown in the image below.

IDE warning when the generated code for a model class does not exist
yet.

这些错误完全正常，很简单，因为这些模型类的生成代码并不存在。要解决这个问题，你需要运行代码生成器来生成序列化数据模板。

These errors are entirely normal and are simply because the generated code for the model class does not exist yet. To resolve this, run the code generator that generates the serialization boilerplate.

有两种方式运行代码生成器。

There are two ways of running the code generator.

一次性代码生成

One-time code generation

通过在项目根目录运行 flutter pub run build_runner build，你可以在任何需要的时候为你的模型生成 JSON 序列化数据代码。这会触发一次构建，遍历源文件，选择相关的文件，然后为它们生成必须的序列化数据代码。

By running flutter pub run build_runner build in the project root, you generate JSON serialization code for your models whenever they are needed. This triggers a one-time build that goes through the source files, picks the relevant ones, and generates the necessary serialization code for them.

虽然这样很方便，但是如果你不需要在每次修改了你的模型类后都要手动构建那将会很棒。

While this is convenient, it would be nice if you did not have to run the build manually every time you make changes in your model classes.

持续生成代码

Generating code continuously

监听器 让我们的源代码生成过程更加方便。它会监听我们项目中的文件变化，并且会在需要的时候自动构建必要的文件。你可以在项目根目录运行 flutter pub run build_runner watch 启动监听。

A watcher makes our source code generation process more convenient. It watches changes in our project files and automatically builds the necessary files when needed. Start the watcher by running flutter pub run build_runner watch in the project root.

启动监听并让它留在后台运行是安全的。

It is safe to start the watcher once and leave it running in the background.

使用 json_serializable 模型

Consuming json_serializable models

为了以 json_serializable 的方式解码 JSON 字符串，你不必对以前的代码做任何的改动。

To decode a JSON string the json_serializable way, you do not have actually to make any changes to our previous code.

Map<String, dynamic> userMap = jsonDecode(jsonString);
var user = User.fromJson(userMap);

编码也是如此。调用 API 和以前一样。

The same goes for encoding. The calling API is the same as before.

String json = jsonEncode(user);

在使用了 json_serializable 后，你可以立马忘掉 User 类中所有手动序列化的 JSON 数据。源代码生成器会创建一个名为 user.g.dart 的文件，它包含了所有必须的序列化数据逻辑。你不必再编写自动化测试来确保序列化数据奏效。现在 由库来负责 确保序列化数据能正确地被转换。

With json_serializable, you can forget any manual JSON serialization in the User class. The source code generator creates a file called user.g.dart, that has all the necessary serialization logic. You no longer have to write automated tests to ensure that the serialization works—it’s now the library’s responsibility to make sure the serialization works appropriately.

为嵌套类 (Nested Classes) 生成代码

Generating code for nested classes

你可能类在代码中用了嵌套类，在你把类作为参数传递给一些服务（比如 Firebase）的时候，你可能会遇到 Invalid argument 错误。

You might have code that has nested classes within a class. If that is the case, and you have tried to pass the class in JSON format as an argument to a service (such as Firebase, for example), you might have experienced an Invalid argument error.

比如下面的这个 Address 类：

Consider the following Address class:

import 'package:json_annotation/json_annotation.dart';
part 'address.g.dart';

@JsonSerializable()
class Address {
  String street;
  String city;

  Address(this.street, this.city);

  factory Address.fromJson(Map<String, dynamic> json) =>
      _$AddressFromJson(json);
  Map<String, dynamic> toJson() => _$AddressToJson(this);
}

一个 Address 类被嵌套在 User 类中使用：

The Address class is nested inside the User class:

import 'package:json_annotation/json_annotation.dart';

import 'address.dart';

part 'user.g.dart';

@JsonSerializable()
class User {
  User(this.name, this.address);

  String name;
  Address address;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

在终端中运行 flutter pub run build_runner build 创建 *.g.dart文件，但私有函数 _$UserToJson() 看起来会像下面这样：

Running flutter pub run build_runner build in the terminal creates the *.g.dart file, but the private _$UserToJson() function looks something like the following:

Map<String, dynamic> _$UserToJson(User instance) => <String, dynamic>{
  'name': instance.name,
  'address': instance.address,
};

现在看起来并没有什么问题，但当你想要打印 (print()) 这个用户对象时：

All looks fine now, but if you do a print() on the user object:

Address address = Address("My st.", "New York");
User user = User("John", address);
print(user.toJson());

结果会是：

The result is:

{name: John, address: Instance of 'address'}

而你期望的输出结果是这样的：

When what you probably want is output like the following:

{name: John, address: {street: My st., city: New York}}

为了得到正常的输出，你需要在类声明之前在 @JsonSerializable 方法加入 explicitToJson: true 参数， User 类现在看起来是这样的：

To make this work, pass explicitToJson: true in the @JsonSerializable() annotation over the class declaration. The User class now looks as follows:

import 'package:json_annotation/json_annotation.dart';

import 'address.dart';

part 'user.g.dart';

@JsonSerializable(explicitToJson: true)
class User {
  User(this.name, this.address);

  String name;
  Address address;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

了解更多信息，请查阅 json_annotation 这个 package 里的 JsonSerializable 类的 explicitToJson 参数等相关文档。

For more information, see explicitToJson in the JsonSerializable class for the json_annotation package.

进一步参考

Further references

更多信息，请查看以下资源：

For more information, see the following resources:

dart:convert 和 JsonCodec 文档
The dart:convert and JsonCodec documentation
Pub 中 json_serializable package
The json_serializable package on pub.dev
GitHub 中 json_serializable 的例子
The json_serializable examples on GitHub

使用 Firestore 调用 Firebase 服务

Firebase 是一个用于开发 BaaS 应用的开发平台，它提供了诸如实时数据库、云存储、鉴权、Crash 上报、机器学习、远程配置以及托管你的静态文件等后台托管服务。

Firebase is a Backend-as-a-Service (BaaS) app development platform that provides hosted backend services such as a realtime database, cloud storage, authentication, crash reporting, machine learning, remote configuration, and hosting for your static files.

Firebase 可以支持 Flutter，如果你想获取更多信息，可以查阅下面这些链接：

Firebase supports Flutter. For more information, see:

FlutterFire 官网
The FlutterFire site
将 Firebase 添加到您的 Flutter 应用
Getting started with Firebase and Flutter
基于 workshop 了解如何在 Flutter 中使用 Firebase
Get to know Firebase for Flutter video workshop based on the codelab
基于 codelab 了解如何在 Flutter 中使用 Firebase
Get to know Firebase for Flutter codelab
在多平台下的 Firebase Futter
Multi Platform Firebase Flutter
使用 Firebase 来部署你的 Flutter Web 应用
Use Firebase to host your Flutter app on the web

当然，Flutter 社区也创建了一些可能会对你有用的文档：

Also, the Flutter community has created docs and videos that you might find useful. Here are a few:

在 Flutter 中使用 Firebase 构建聊天应用（文章）
Building chat app with Flutter and Firebase
在你的 Flutter 应用中使用 Firestore 作为后端（视频）
Using Firestore as a backend to your Flutter app (video)
在 Flutter 中使用 Firebase 进行验证的代码演示（视频）
Live Coding Firebase Authentication with Flutter (video)
使用 Flutter & Firebase 进行验证 01（视频）
Flutter & Firebase Auth 01 (video)
Flutter: Firebase Tutorial Part 1 - Auth and Sign in (video)

[Flutter: Firebase 教程第一部分验证与登陆]video4（视频）

无障碍

辅助功能检测
Inspecting accessibility support
大字体
Large fonts
- 给开发者的提示
  Tips for developers
- 例子
  Example
读屏器
Screen readers
高对比度
Sufficient contrast
- 给开发者的提示
  Tips for developers
思考如何构建无障碍应用
Building with accessibility in mind
在 Web 上测试无障碍：
Testing accessibility on web:
无障碍发布清单
Accessibility release checklist
更多信息
More information

确保你的应用能够被广泛的用户使用是构建高质量应用程序至关重要的一点。如果你的应用设计不佳，可能会无法覆盖到所有年龄段的人。联合国关于残疾人权利规定了道德和法律必须确保信息系统能够普遍使用。世界各地也都要求提供无障碍的环境；同样，公司也认识到了最大限度覆盖服务的优势所在。

Ensuring apps are accessible to a broad range of users is an essential part of building a high-quality app. Applications that are poorly designed create barriers to people of all ages. The UN Convention on the Rights of Persons with Disabilities states the moral and legal imperative to ensure universal access to information systems; countries around the world enforce accessibility as a requirement; and companies recognize the business advantages of maximizing access to their services.

我们强烈建议你将辅助功能清单添加到发布应用前的关键指标。 Flutter 始终致力于支持开发者能够使它的应用更易于访问，其中就包括了由底层操作系统提供的一流的无障碍支持，包括：

We strongly encourage you to include an accessibility checklist as a key criteria before shipping your app. Flutter is committed to supporting developers in making their apps more accessible, and includes first-class framework support for accessibility in addition to that provided by the underlying operating system, including:

大字体
使用用户指定的字体大小呈现文本 widget

Large fonts
Render text widgets with user-specified font sizes

读屏器
通过语音反馈传达用户界面的内容

Screen readers
Communicate spoken feedback about UI contents

高对比度
在渲染 widget 时，使用具有高对比度的颜色

Sufficient contrast
Render widgets with colors that have sufficient contrast

详细关于这个特性的讨论，请继续阅读。

Details of these features are discussed below.

辅助功能检测

Inspecting accessibility support

关于无障碍功能检测的细节，我们将在下面讨论。除了测试这些特定主题外，我们还建议您使用自动辅助功能扫描程序：

Details of these are discussed below. In addition to testing for these specific topics, we recommend using automated accessibility scanners:

对于 Android:
For Android:
1. 在 Android 上安装辅助扫描程序
  Install the Accessibility Scanner for Android
2. 通过 设置 > 辅助 > 辅助扫描仪 > 开启在 Android 启用辅助功能扫描程序
  Enable the Accessibility Scanner from Android Settings > Accessibility > Accessibility Scanner > On
3. 在导航栏找到辅助扫描仪复选框按钮启动扫描
  Navigate to the Accessibility Scanner ‘checkbox’ icon button to initiate a scan
对于 iOS:
For iOS:
1. 在 Xcode 中打开 Flutter 应用程序的 iOS 文件夹
  Open the iOS folder of your Flutter app in Xcode
2. 找到模拟器，然后单击运行按钮
  Select a Simulator as the target, and click Run button
3. 在 Xcode 选择 Xcode > 开发者工具 > 辅助检查器
  In Xcode, select Xcode > Open Developer Tools > Accessibility Inspector
4. 在辅助检查器中，选择 检查> 启用点检查，然后运行 Flutter 应用程序，选择各种用户界面元素来检查其辅助功能
  In the Accessibility Inspector, select Inspection > Enable Point to Inspect, and then select the various user interface elements in running Flutter app to inspect their accessibility attributes
5. 在辅助检查器中，选择工具栏中的审核，然后选择运行音频”来获取潜在问题的报告
  In the Accessibility Inspector, select Audit in the toolbar, and then select Run Audit to get a report of potential issues
对于 web:
For web:
1. 打开 Chrome 开发者工具（或其他浏览器中的类似工具）
  Open Chrome DevTools (or similar tools in other browsers)
2. 检查包含 Flutter 生成的 ARIA 属性的 HTML 树。
  Inspect the HTML tree containing the ARIA attributes generated by Flutter.
3. 在 Chrome 中，「Elements」选项卡中有一个「Accessbility」子选项卡，可用于检查导出到语义树的数据。
  In Chrome, the “Elements” tab has a “Accessbility” sub-tab that can be used to inspect the data exported to semantics tree

大字体

Large fonts

Android 和 iOS 都包含配置应用程序所需字体大小的系统设置。在确定字体大小时， Flutter 文本 widget 会遵循当前系统设置。

Both Android and iOS contain system settings to configure the desired font sizes used by apps. Flutter text widgets respect this OS setting when determining font sizes.

给开发者的提示

Tips for developers

Flutter 会根据操作系统设置自动计算字体大小。但是，作为开发人员，你应确保在增加字体大小时，你的页面有足够的空间来呈现其所有内容。例如，你可以在小屏幕上设置最大的字体来测试你应用上的全部内容。

Font sizes are calculated automatically by Flutter based on the OS setting. However, as a developer you should make sure your layout has enough room to render all its contents when the font sizes are increased. For example, you can test all parts of your app on a small-screen device configured to use the largest font setting.

例子

Example

以下两个屏幕截图分别显示了使用默认 iOS 字体设置呈现的标准 Flutter 应用程序，和使用 iOS 辅助功能设置中选择的最大字体设置呈现的 Flutter 应用程序。

The following two screenshots show the standard Flutter app template rendered with the default iOS font setting, and with the largest font setting selected in iOS accessibility settings.

读屏器

Screen readers

对于移动设备，读屏器（TalkBack、VoiceOver）可以使视障用户能够获得有关屏幕内容的语音反馈，并通过移动设备上的手势和桌面上的键盘快捷键与 UI 进行交互。在你的移动设备上打开 VoiceOver 或 TalkBack 并浏览你的应用程序。

For mobile, screen readers (TalkBack, VoiceOver) enable visually impaired users to get spoken feedback about the contents of the screen and interact with the UI via gestures on mobile and keyboard shortcuts on desktop. Turn on VoiceOver or TalkBack on your mobile device and navigate around your app.

对于 Web，目前支持以下屏幕阅读器：

For web, the following screen readers are currently supported:

移动浏览器：

Mobile Browsers:

iOS - VoiceOver
Android - TalkBack

桌面浏览器：

Desktop Browsers:

MacOS - VoiceOver
Windows - JAWs & NVDA

Web 上的读屏器用户需要点击「启用辅助功能」按钮来构建语义树。如果你使用下面这个 API 以编程方式为你的应用程序自动启用辅助功能，则用户可以跳过此步骤：

Screen Readers users on web will need to toggle “Enable accessibility” button to build the semantics tree. Users can skip this step if you programmatically auto-enable accessibility for your app using this API:

RendererBinding.instance.setSemanticsEnabled(true)

查看此视频演示，了解 Victor Tsaran，他领导了 Material Design 的辅助功能计划，并在 Flutter Gallery Web 应用程序中使用了 VoiceOver。

Check out this video demo to see Victor Tsaran, who leads the Accessibility program for Material Design, using VoiceOver with the Flutter Gallery web app.

Flutter 的标准 widget 会自动生成无障碍树。但是，如果你的应用需要不同的东西，则可以使用语义小部件来自定义您应用程序的无障碍体验。

Flutter’s standard widgets generate an accessibility tree automatically. However, if your app needs something different, it can be customized using the Semantics widget.

高对比度

Sufficient contrast

高对比度能够使文本和图像更易于阅读。除了使具有各种视觉障碍的用户受益外，高对比度也能够帮助所有用户在极端光照条件下 (例如在直射阳光下或在低亮度显示器上) 观看设备上的界面。

Sufficient color contrast makes text and images easier to read. Along with benefitting users with various visual impairments, sufficient color contrast helps all users when viewing an interface on devices in extreme lighting conditions, such as when exposed to direct sunlight or on a display with low brightness.

W3C 建议:

The W3C recommends:

小文本至少 4.5:1 (低于 18 像素常规或 14 像素粗体)
At least 4.5:1 for small text (below 18 point regular or 14 point bold)
大文本至少 3.0:1 (18 像素及以上常规或 14 像素及以上粗体)
At least 3.0:1 for large text (18 point and above regular or 14 point and above bold)

给开发者的提示

Tips for developers

确保你包含的任何图像都具有较高的对比度。

Make sure any images you include have sufficient contrast.

在 widget 上指定颜色时，请确保在前景色和背景色之间具备足够的对比度。

When specifying colors on widgets, make sure sufficient contrast is used between foreground and background color selections.

思考如何构建无障碍应用

Building with accessibility in mind

确保你的应用能够被所有人使用，这意味着你需要从一开始就考虑到无障碍。对于一些应用，说起来容易做起来难。在下面的视频中，我们的两名工程师从一个无障碍状态中获取了一个 Flutter 内置的 widget，以提供更加便捷的体验。

Ensuring your app can be used by everyone means building accessibility into it from the start. For some apps, that’s easier said than done. In the video below, two of our engineers take a mobile app from a dire accessibility state to one that takes advantage of Flutter’s built-in widgets to offer a dramatically more accessible experience.

在 Web 上测试无障碍：

Testing accessibility on web:

您可以通过在配置文件和发布模式下使用以下命令行标志可视化为你的 Web 应用程序创建的语义节点来调试无障碍：

You can debug accessibility by visualizing the semantic nodes created for your web app using the following command line flag in profile and release modes:

$ flutter run -d chrome --profile \ --dart-define=FLUTTER_WEB_DEBUG_SHOW_SEMANTICS=true

标记激活后，语义节点出现在 widget 的顶部；你可以验证语义元素是否放置在应有的位置。如果语义节点放置不正确，请提交错误报告。

With the flag activated, the semantic nodes appear on top of the widgets; you can verify that the semantic elements are placed where they should be. If the semantic nodes are incorrectly placed, please file a bug report.

无障碍发布清单

Accessibility release checklist

这里是一些应用发布前的你需要考虑的部分清单。

Here is a non-exhaustive list of things to consider as you prepare your app for release.

主动交互。确保所有可以交互的地方都会给予反馈。任何按钮在按下之后都会做点什么。例如，如果你有一个“onPressed”事件的无操作回调，请改为显示一个“SnackBar”，并告诉用户刚才按下了哪个控件。
Active interactions. Ensure that all active interactions do something. Any button that can be pushed should do something when pushed. For example, if you have a no-op callback for an onPressed event, change it to show a SnackBar on the screen explaining which control you just pushed.
屏幕阅读测试。屏幕阅读器应该能够让你在点击控件时描述页面上所有的控件，并且描述应易于理解。请使用 TalkBack（Android）以及 VoiceOver (iOS) 测试你的应用。
Screen reader testing. The screen reader should be able to describe all controls on the page when you tap on them, and the descriptions should be intelligible. Test your app with TalkBack (Android) and VoiceOver (iOS).

对比度。我们建议你至少将控件或文本与背景之间的比例设为 4.5 : 1，禁用的组件除外。图片也应该经过审核足够的对比度。
Contrast ratios. We encourage you to have a contrast ratio of at least 4.5:1 between controls or text and the background, with the exception of disabled components. Images should also be vetted for sufficient contrast.
上下文切换。当用户输入信息时你不应改变其信息。通常来说，widget 应该避免在没有任何确认动作的情况下更改用户的上下文。
Context switching. Nothing should change the user’s context automatically while typing in information. Generally, the widgets should avoid changing the user’s context without some sort of confirmation action.
可点击的目标。所有可点击的目标平均至少应为 48x48 像素。
Tappable targets. All tappable targets should be at least 48x48 pixels.
错误。所有重要动作应该能够被撤销。在有限范围内显示错误原因，如果可能的话，提供订正建议。
Errors. Important actions should be able to be undone. In fields that show errors, suggest a correction if possible.
色觉不足测试。控件应该可用并且在色盲和灰度模式下清晰可见。
Color vision deficiency testing. Controls should be usable and legible in colorblind and grayscale modes.
比例系数。文本大小和显示比例的用户界面应保持清晰易用。
Scale factors. The UI should remain legible and usable at very large scale factors for text size and display scaling.

More information

如果你希望了解更多，尤其是如何配置 semantics tree，请查看如下社区成员贡献的文章：

For more information, particularly about how to configure the semantics tree, see the following articles written by community members:

Flutter 应用里的国际化

Flutter 应用本地化介绍
Introduction to localizations in Flutter
定制的进阶操作
Advanced topics for further customization
Flutter 里的国际化是如何工作的
How internationalization in Flutter works
其他的国际化方法
Alternative internationalization workflows
- 应用程序本地化资源的替代类
  An alternative class for the app’s localized resources
- 附录：使用 Dart intl 工具
  Using the Dart intl tools

如果你的 app 会部署给说其他语言的用户使用，那么你就需要对它进行国际化。这就意味着你在编写 app 的时候，需要采用一种容易对它进行本地化的方式进行开发，这种方式让你能够为每一种语言或者 app 所支持的语言环境下的文本和布局等进行本地化。 Flutter 提供了 widgets 和类来帮助开发者进行国际化，当然 Flutter 库本身就是国际化的。

If your app might be deployed to users who speak another language then you’ll need to internationalize it. That means you need to write the app in a way that makes it possible to localize values like text and layouts for each language or locale that the app supports. Flutter provides widgets and classes that help with internationalization and the Flutter libraries themselves are internationalized.

由于大多数应用程序都是以这种方式编写的，因此该页面主要介绍了使用 MaterialApp 和 CupertinoApp 对 Flutter 应用程序进行本地化所需的概念和工作流程。但是，使用较低级别的 WidgetsApp 类编写的应用程序也可以使用相同的类和逻辑进行国际化。

This page covers concepts and workflows necessary to localize a Flutter application using the MaterialApp and CupertinoApp classes, as most apps are written that way. However, applications written using the lower level WidgetsApp class can also be internationalized using the same classes and logic.

国际化的 app 示例

Sample internationalized apps

如果你想通过阅读已经国际化的 Flutter app 代码来开始的话，这里有两个小例子。第一个例子是一个尽可能简单的实现。第二个例子使用了 intl package 提供的 API 和工具。如果你还不熟悉 Dart 的 intl 包，请查看使用 Dart intl 工具。

If you’d like to start out by reading the code for an internationalized Flutter app, here are two small examples. The first one is intended to be as simple as possible, and the second one uses the APIs and tools provided by the intl package. If Dart’s intl package is new to you, see Using the Dart intl tools.

Flutter 应用本地化介绍

Introduction to localizations in Flutter

本节主要介绍如何对 Flutter 应用进行国际化，以及针对目标平台需要设置的其他内容。

This section provides a tutorial on how to internationalize a Flutter application, along with any additional setup that a target platform might require.

配置一个国际化的 app：flutter_localizations package

Setting up an internationalized app: the Flutter_localizations package

默认情况下，Flutter 只提供美式英语的本地化。如果想要添加其他语言，你的应用必须指定额外的 MaterialApp 或者 CupertinoApp 属性并且添加一个名为 flutter_localizations 的 package。截至到 2020 年 11 月份，这个 package 已经支持大约 78 种语言。

By default, Flutter only provides US English localizations. To add support for other languages, an application must specify additional MaterialApp (or CupertinoApp) properties, and include a package called flutter_localizations. As of November 2020, this package supports 78 languages.

想要使用 flutter_localizations 的话，你需要在 pubspec.yaml 文件中添加它作为依赖：

To use flutter_localizations, add the package as a dependency to your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations: # Add this line
    sdk: flutter         # Add this line

下一步，先运行 pub get packages，然后引入 flutter_localizations 库，然后为 MaterialApp 指定 localizationsDelegates 和 supportedLocales：

Next, run pub get packages, then import the flutter_localizations library and specify localizationsDelegates and supportedLocales for MaterialApp:

import 'package:flutter_localizations/flutter_localizations.dart';

return const MaterialApp(
  title: 'Localizations Sample App',
  localizationsDelegates: [
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: [
    Locale('en', ''), // English, no country code
    Locale('es', ''), // Spanish, no country code
  ],
  home: MyHomePage(),
);

引入 flutter_localizations package 并添加了上面的代码之后， Material 和 Cupertino 包现在应该被正确地本地化为 78 个受支持的语言环境之一。 widget 应当与本地化信息保持同步，并具有正确的从左到右或从右到左的布局。

After introducing the flutter_localizations package and adding the code above, the Material and Cupertino packages should now be correctly localized in one of the 78 supported locales. Widgets should be adapted to the localized messages, along with correct left-to-right and right-to-left layout.

你可以尝试将目标平台的语言环境切换为西班牙语（es），然后应该可以发现信息已经被本地化了。

Try switching the target platform’s locale to Spanish (es) and notice that the messages should be localized.

基于 WidgetsApp 构建的 app 在添加语言环境时，除了 GlobalMaterialLocalizations.delegate 不需要之外，其他的操作是类似的。

Apps based on WidgetsApp are similar except that the GlobalMaterialLocalizations.delegate isn’t needed.

虽然 语言环境 (Locale) 默认的构造函数是完全没有问题的，但是还是建议大家使用 Locale.fromSubtags 的构造函数，因为它支持设置文字代码。

The full Locale.fromSubtags constructor is preferred as it supports scriptCode, though the Locale default constructor is still fully valid.

localizationDelegates 数组是用于生成本地化值集合的工厂。 GlobalMaterialLocalizations.delegate 为 Material 组件库提供本地化的字符串和一些其他的值。 GlobalWidgetsLocalizations.delegate 为 widgets 库定义了默认的文本排列方向，由左到右或者由右到左。

The elements of the localizationsDelegates list are factories that produce collections of localized values. GlobalMaterialLocalizations.delegate provides localized strings and other values for the Material Components library. GlobalWidgetsLocalizations.delegate defines the default text direction, either left-to-right or right-to-left, for the widgets library.

想知道更多关于这些 app 属性，它们依赖的类型以及那些国际化的 Flutter app 通常是如何组织的，可以继续阅读下面内容。

More information about these app properties, the types they depend on, and how internationalized Flutter apps are typically structured, can be found below.

添加您自己的本地化信息

Adding your own localized messages

引入 flutter_localizations package 后，请按照以下说明将本地化的文本添加到您的应用程序。

Once the flutter_localizations package is added, use the following instructions to add localized text to your application.

将 intl package 添加到 pubspec.yaml 文件中：

Add the intl package to the pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: ^0.17.0 # Add this line

另外，在 pubspec.yaml 文件中，启用 generate 标志。该设置项添加在 pubspec 中 Flutter 部分，通常处在 pubspec 文件中后面的部分。
Also, in the pubspec.yaml file, enable the generate flag. This is added to the section of the pubspec that is specific to Flutter, and usually comes later in the pubspec file.
```
# The following section is specific to Flutter.
flutter:
  generate: true # Add this line
```
在 Flutter 项目的根目录中添加一个新的 yaml 文件，命名为 l10n.yaml，其内容如下：
Add a new yaml file to the root directory of the Flutter project called l10n.yaml with the following content:
```
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
```
该文件用于配置本地化工具；在上面的示例中，指定输入文件在 ${FLUTTER_PROJECT}/lib/l10n 中，app_en.arb 文件提供模板，生成的本地化文件在 app_localizations.dart 文件中。
This file configures the localization tool; in this example, the input files are located in ${FLUTTER_PROJECT}/lib/l10n, the app_en.arb file provides the template, and the generated localizations are placed in the app_localizations.dart file.
在 ${FLUTTER_PROJECT}/lib/l10n 中，添加 app_en.arb 模板文件。如下：
In ${FLUTTER_PROJECT}/lib/l10n, add the app_en.arb template file. For example:
```
{
    "helloWorld": "Hello World!",
    "@helloWorld": {
      "description": "The conventional newborn programmer greeting"
    }
}
```
接下来，在同一目录中添加一个 app_es.arb 文件，对同一条信息做西班牙语的翻译：
Next, add an app_es.arb file in the same directory for Spanish translation of the same message:
```
{
    "helloWorld": "¡Hola Mundo!"
}
```
要测试本地化工具，可以运行您的应用程序。您将在 ${FLUTTER_PROJECT}/.dart_tool/flutter_gen/gen_l10n 中看到生成的文件。
Now, run your app so that codegen takes place. You should see generated files in ${FLUTTER_PROJECT}/.dart_tool/flutter_gen/gen_l10n.

在调用 MaterialApp 的构造函数时候，添加 import 语句，导入 app_localizations.dart 和 AppLocalizations.delegate。

Add the import statement on app_localizations.dart and AppLocalizations.delegate in your call to the constructor for MaterialApp.

import 'package:flutter_gen/gen_l10n/app_localizations.dart';

return const MaterialApp(
  title: 'Localizations Sample App',
  localizationsDelegates: [
    AppLocalizations.delegate, // Add this line
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: [
    Locale('en', ''), // English, no country code
    Locale('es', ''), // Spanish, no country code
  ],
  home: MyHomePage(),
);

在你应用的任何地方，都使用 AppLocalizations，这里它被用于在 Text widget 里展示翻译过的消息。
Use AppLocalizations anywhere in your app. Here, the translated message is used in a Text widget.
```
Text(AppLocalizations.of(context)!.helloWorld);
```
您也可以使用生成的 localizationsDelegates 和 supportedLocales 列表，而不是手动提供它们。
You can also use the generated localizationsDelegates and supportedLocales list instead of providing them manually.
```
const MaterialApp(
  title: 'Localizations Sample App',
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  supportedLocales: AppLocalizations.supportedLocales,
);
```
如果目标设备的语言环境设置为英语，此代码生成的 Text widget 会展示「Hello World!」。如果目标设备的语言环境设置为西班牙语，则展示「Hola Mundo!」，在 arb 文件中，每个条目的键值都被用作 getter 的方法名称，而该条目的值则表示本地化的信息。
This code generates a Text widget that displays “Hello World!” if the target device’s locale is set to English, and “¡Hola Mundo!” if the target device’s locale is set to Spanish. In the arb files, the key of each entry is used as the method name of the getter, while the value of that entry contains the localized message.

要查看使用该工具的示例 Flutter 应用，请参阅 gen_l10n_example。

To see a sample Flutter app using this tool, please see gen_l10n_example.

如需本地化设备应用描述，你可以将本地化后的字符串传递给 MaterialApp.onGenerateTitle:

To localize your device app description, you can pass in the localized string into MaterialApp.onGenerateTitle:

return MaterialApp(
  onGenerateTitle: (BuildContext context) =>
      DemoLocalizations.of(context).title,

有关本地化工具的更多信息，例如处理 DateTime 和复数，请参见国际化用户指南。

For more information about the localization tool, such as dealing with DateTime and handling plurals, see the Internationalization User’s Guide.

iOS 本地化：更新 iOS app bundle

Localizing for iOS: Updating the iOS app bundle

iOS 应用在内置于应用程序包中的 Info.plist 文件中定义了关键的应用程序元数据，其中包括了受支持的语言环境，要配置您的应用支持的语言环境，请按照以下步骤进行操作：

iOS applications define key application metadata, including supported locales, in an Info.plist file that is built into the application bundle. To configure the locales supported by your app, use the following instructions:

打开项目的 ios/Runner.xcworkspace Xcode 文件。
Open your project’s ios/Runner.xcworkspace Xcode file.
在 Project Navigator 中，打开 Runner 项目的 Runner 文件夹下的 Info.plist 文件。
In the Project Navigator, open the Info.plist file under the Runner project’s Runner folder.
选择 Information Property List 项。然后从 Editor 菜单中选择 Add Item，接着从弹出菜单中选择 Localizations。
Select the Information Property List item. Then select Add Item from the Editor menu, and select Localizations from the pop-up menu.
选择并展开新创建的 Localizations 项。对于您的应用程序支持的每种语言环境，请添加一个新项，然后从 Value 字段中的弹出菜单中选择要添加的语言环境。该列表应需要与 supportedLocales 参数中列出的语言一致。
Select and expand the newly-created Localizations item. For each locale your application supports, add a new item and select the locale you wish to add from the pop-up menu in the Value field. This list should be consistent with the languages listed in the supportedLocales parameter.
添加所有受支持的语言环境后，保存文件。
Once all supported locales have been added, save the file.

定制的进阶操作

Advanced topics for further customization

本节介绍自定义本地 Flutter 应用程序的其他方法。

This section covers additional ways to customize a localized Flutter application.

高级语言环境定义

Advanced locale definition

一些具有着多个变体的语言仅用 languageCode 来区分是不够充分的。

Some languages with multiple variants require more than just a language code to properly differentiate.

例如，在多语言应用开发这个话题里，如果要更好的区分具有多种语言变体的中文，则需要指定其 languageCode、scriptCode 和 countryCode。因为目前有两种主要的，且存在地区使用差异的中文书写系统：简体和繁体。

For example, fully differentiating all variants of Chinese requires specifying the language code, script code, and country code. This is due to the existence of simplified and traditional script, as well as regional differences in the way characters are written within the same script type.

为了让 CN、TW 和 HK 能够更充分地表示到每个中文变体，构建应用时，设定支持的语言列表可以参考如下代码：

In order to fully express every variant of Chinese for the country codes CN, TW, and HK, the list of supported locales should include:

supportedLocales: [
  Locale.fromSubtags(languageCode: 'zh'), // generic Chinese 'zh'
  Locale.fromSubtags(
      languageCode: 'zh',
      scriptCode: 'Hans'), // generic simplified Chinese 'zh_Hans'
  Locale.fromSubtags(
      languageCode: 'zh',
      scriptCode: 'Hant'), // generic traditional Chinese 'zh_Hant'
  Locale.fromSubtags(
      languageCode: 'zh',
      scriptCode: 'Hans',
      countryCode: 'CN'), // 'zh_Hans_CN'
  Locale.fromSubtags(
      languageCode: 'zh',
      scriptCode: 'Hant',
      countryCode: 'TW'), // 'zh_Hant_TW'
  Locale.fromSubtags(
      languageCode: 'zh',
      scriptCode: 'Hant',
      countryCode: 'HK'), // 'zh_Hant_HK'
],

代码里这几组明确和完整的定义，可以确保你的应用为各种不同首选语言环境的用户提供更加精细化的本地化内容。如果用户没有指定首选的语言环境，那么我们就会使用最近的匹配，这可能与用户的期望会有差异。 Flutter 只会解析定义在 supportedLocales 里面的语言环境。对于那些常用语言，Flutter 为本地化内容提供了文字代码级别的区分。查看 Localizations 了解 Flutter 是如何解析支持的语言环境和首选的语言环境的。

This explicit full definition ensures that your app can distinguish between and provide the fully nuanced localized content to all combinations of these country codes. If a user’s preferred locale is not specified, then the closest match is used instead, which likely contains differences to what the user expects. Flutter only resolves to locales defined in supportedLocales. Flutter provides scriptCode-differentiated localized content for commonly used languages. See Localizations for information on how the supported locales and the preferred locales are resolved.

虽然中文是最主要的一个示例，但是其他语言如法语（fr_FR，fr_CA 等等）也应该为了更细致的本地化而做完全的区分。

Although Chinese is a primary example, other languages like French (fr_FR, fr_CA) should also be fully differentiated for more nuanced localization.

Tracking the locale: The Locale class and the Localizations widget

Locale 类用来识别用户的语言。移动设备支持为所有的应用设置语言环境，经常是通过系统设置菜单来进行操作。设置完之后，国际化的 app 就会展示成对应特定语言环境的值。例如，如果用户把设备的语言环境从英语切换到法语，显示 “Hello World” 的文本 widget 会使用 “Bonjour le monde” 进行重建。

The Locale class identifies the user’s language. Mobile devices support setting the locale for all applications, usually using a system settings menu. Internationalized apps respond by displaying values that are locale-specific. For example, if the user switches the device’s locale from English to French, then a Text widget that originally displayed “Hello World” would be rebuilt with “Bonjour le monde”.

Localizations widget 定义了它的子节点的语言环境和依赖的本地化的资源。 WidgetsApp 创建了一个本地化的 widget，如果系统的语言环境变化了，它会重建这个 widget。

The Localizations widget defines the locale for its child and the localized resources that the child depends on. The WidgetsApp widget creates a Localizations widget and rebuilds it if the system’s locale changes.

你可以通过调用 Localizations.localeOf() 方法来查看 app 当前的语言环境。

You can always lookup an app’s current locale with Localizations.localeOf():

Locale myLocale = Localizations.localeOf(context);

Specifying the app’s supportedLocales parameter

Although the flutter_localizations library currently supports 78 languages and language variants, only English language translations are available by default. It’s up to the developer to decide exactly which languages to support.

The MaterialApp supportedLocales parameter limits locale changes. When the user changes the locale setting on their device, the app’s Localizations widget only follows suit if the new locale is a member of this list. If an exact match for the device locale isn’t found, then the first supported locale with a matching languageCode is used. If that fails, then the first element of the supportedLocales list is used.

An app that wants to use a different “locale resolution” method can provide a localeResolutionCallback. For example, to have your app unconditionally accept whatever locale the user selects:

MaterialApp(
  localeResolutionCallback: (
    Locale? locale,
    Iterable<Locale> supportedLocales,
  ) {
    return locale;
  },
);

Flutter 里的国际化是如何工作的

How internationalization in Flutter works

本节涵盖了 Flutter 中本地化工作的技术细节，如果你计划使用自定的一套本地化消息，下面的内容会很有帮助。反之则可以跳过本节。

This section covers the technical details of how localizations work in Flutter. If you’re planning on supporting your own set of localized messages, the following content would be helpful. Otherwise, you can skip this section.

加载和获取本地化值

Loading and retrieving localized values

我们使用 Localizations widget 来加载和查询那些包含本地化值集合的对象。 app 通过调用 Localizations.of(context,type) 来引用这些对象。如果设备的语言环境变化了，Localizations widget 会自动地加载新的语言环境的值，然后重建那些使用了语言环境的 widget。这是因为 Localizations 像继承 widget 一样执行。当一个构建过程涉及到继承 widget，对继承 widget 的隐式依赖就创建了。当一个继承 widget 变化了（即 Localizations widget 的语言环境变化），它的依赖上下文就会被重建。

The Localizations widget is used to load and lookup objects that contain collections of localized values. Apps refer to these objects with Localizations.of(context,type). If the device’s locale changes, the Localizations widget automatically loads values for the new locale and then rebuilds widgets that used it. This happens because Localizations works like an InheritedWidget. When a build function refers to an inherited widget, an implicit dependency on the inherited widget is created. When an inherited widget changes (when the Localizations widget’s locale changes), its dependent contexts are rebuilt.

本地化的值是通过使用 Localizations widget 的 LocalizationsDelegate 加载的。每一个 delegate 必须定义一个异步的 load() 方法。这个方法生成了一个封装本地化值的对象，通常这些对象为每个本地化的值定义了一个方法。

Localized values are loaded by the Localizations widget’s list of LocalizationsDelegates. Each delegate must define an asynchronous load() method that produces an object that encapsulates a collection of localized values. Typically these objects define one method per localized value.

在一个大型的 app 中，不同的模块或者 package 需要和它们对应的本地化资源打包在一起。这就是为什么 Localizations widget 管理着对象的一个对应表，每个 LocalizationsDelegate 对应一个对象。为了获得由 LocalizationsDelegate 的 load 方法生成的对象，你需要指定一个构建上下文 (BuildContext) 和对象的类型。

In a large app, different modules or packages might be bundled with their own localizations. That’s why the Localizations widget manages a table of objects, one per LocalizationsDelegate. To retrieve the object produced by one of the LocalizationsDelegate’s load methods, you specify a BuildContext and the object’s type.

例如，Material 组件 widget 的本地化字符串是由 MaterialLocalizations 类定义的。这个类的实例是由 [MaterialApp 类提供的一个 LocalizationDelegate 方法创建的，它们可以通过 Localizations.of 方法获得。

For example, the localized strings for the Material Components widgets are defined by the MaterialLocalizations class. Instances of this class are created by a LocalizationDelegate provided by the MaterialApp class. They can be retrieved with Localizations.of():

Localizations.of<MaterialLocalizations>(context, MaterialLocalizations);

因为这个特定的 Localizations.of() 表达式经常使用，所以 MaterialLocalizations 类提供了一个快捷访问：

This particular Localizations.of() expression is used frequently, so the MaterialLocalizations class provides a convenient shorthand:

static MaterialLocalizations of(BuildContext context) {
  return Localizations.of<MaterialLocalizations>(context, MaterialLocalizations);
}

/// References to the localized values defined by MaterialLocalizations
/// are typically written like this:

tooltip: MaterialLocalizations.of(context).backButtonTooltip,

为 app 的本地化资源定义一个类

Defining a class for the app’s localized resources

综合所有这些在一起，一个需要国际化的 app 经常以一个封装 app 本地化值的类开始的。下面是使用这种类的典型示例。

Putting together an internationalized Flutter app usually starts with the class that encapsulates the app’s localized values. The example that follows is typical of such classes.

此示例 app 的完整的源码。

Complete source code for the intl_example for this app.

这个示例是基于 intl package 提供的 API 和工具开发的， app 本地化资源的替代方法里面讲解了一个不依赖于 intl package 的示例。

This example is based on the APIs and tools provided by the intl package. An alternative class for the app’s localized resources describes an example that doesn’t depend on the intl package.

DemoLocalizations 类包含了 app 语言环境内支持的已经翻译成了本地化语言的字符串（本例子只有一个）。它通过调用由 Dart 的 intl package 生成的 initializeMessages() 方法来加载翻译好的字符串，然后使用 Intl.message() 来查阅它们。

The DemoLocalizations class defined below contains the app’s strings (just one for the example) translated into the locales that the app supports. It uses the initializeMessages() function generated by Dart’s intl package, Intl.message(), to look them up.

class DemoLocalizations {
  DemoLocalizations(this.localeName);

  static Future<DemoLocalizations> load(Locale locale) {
    final String name =
        locale.countryCode == null || locale.countryCode!.isEmpty
            ? locale.languageCode
            : locale.toString();
    final String localeName = Intl.canonicalizedLocale(name);

    return initializeMessages(localeName).then((_) {
      return DemoLocalizations(localeName);
    });
  }

  static DemoLocalizations of(BuildContext context) {
    return Localizations.of<DemoLocalizations>(context, DemoLocalizations)!;
  }

  final String localeName;

  String get title {
    return Intl.message(
      'Hello World',
      name: 'title',
      desc: 'Title for the Demo application',
      locale: localeName,
    );
  }
}

基于 intl package 的类引入了一个生成好的信息目录，它提供了 initializeMessage() 方法和 Intl.message() 方法的每个语言环境的备份存储。 intl 工具通过分析包含 Intl.message() 调用类的源码生成这个信息目录。在当前情况下，就是 DemoLocalizations 的类（包含了 Intl.message() 调用）。

A class based on the intl package imports a generated message catalog that provides the initializeMessages() function and the per-locale backing store for Intl.message(). The message catalog is produced by an intl tool that analyzes the source code for classes that contain Intl.message() calls. In this case that would just be the DemoLocalizations class.

添加支持新的语言

Adding support for a new language

如果你要开发一个 app 需要支持的语言不在 GlobalMaterialLocalizations 当中，那就需要做一些额外的工作：它必须提供大概 70 个字和词还有日期以及符号的翻译（本地化）。

An app that needs to support a language that’s not included in GlobalMaterialLocalizations has to do some extra work: it must provide about 70 translations (“localizations”) for words or phrases and the date patterns and symbols for the locale.

举个例子，我们将给大家展示如何支持挪威尼诺斯克语。

See the following for an example of how to add support for the Norwegian Nynorsk language.

我们需要定义一个新的 GlobalMaterialLocalizations 子类，它定义了 Material 库依赖的本地化资源。同时，我们也必须定义一个新的 LocalizationsDelegate 子类，它是给 GlobalMaterialLocalizations 子类作为一个工厂使用的。

A new GlobalMaterialLocalizations subclass defines the localizations that the Material library depends on. A new LocalizationsDelegate subclass, which serves as factory for the GlobalMaterialLocalizations subclass, must also be defined.

这是支持添加一种新语言的一个完整例子的源码，相对实际上要翻译的尼诺斯克语数量，我们只翻译了一小部分。

Here’s the source code for the complete add_language example, minus the actual Nynorsk translations.

这个特定语言环境的 GlobalMaterialLocalizations 子类被称为 NnMaterialLocalizations， LocalizationsDelegate 子类被称为 _NnMaterialLocalizationsDelegate。 BeMaterialLocalizations.delegate 是 delegate 的一个实例，这就是 app 使用这些本地化所需要的全部。

The locale-specific GlobalMaterialLocalizations subclass is called NnMaterialLocalizations, and the LocalizationsDelegate subclass is _NnMaterialLocalizationsDelegate. The value of NnMaterialLocalizations.delegate is an instance of the delegate, and is all that’s needed by an app that uses these localizations.

delegate 类包括基本的日期和数字格式的本地化。其他所有的本地化是由 BeMaterialLocalizations 里面的 String 字符串值属性的 getters 所定义的，像下面这样：

The delegate class includes basic date and number format localizations. All of the other localizations are defined by String valued property getters in NnMaterialLocalizations, like this:

@override
String get moreButtonTooltip => r'More';

@override
String get aboutListTileTitleRaw => r'About $applicationName';

@override
String get alertDialogLabel => r'Alert';

当然，这些都是英语翻译。为了完成本地化操作，你需要把每一个 getter 的返回值翻译成合适的新挪威语 (Nynorsk) 字符串。

These are the English translations, of course. To complete the job you need to change the return value of each getter to an appropriate Nynorsk string.

像 r'About $applicationName' 一样，这些带 r 前缀的 getters 返回的是原始的字符串，因为有一些时候这些字符串会包含一些带有 $ 前缀的变量。通过调用带参数的本地化方法，这些变量会被替换：

The getters return “raw” Dart strings that have an r prefix, like r'About $applicationName', because sometimes the strings contain variables with a $ prefix. The variables are expanded by parameterized localization methods:

@override
String get pageRowsInfoTitleRaw => r'$firstRow–$lastRow of $rowCount';

@override
String get pageRowsInfoTitleApproximateRaw =>
    r'$firstRow–$lastRow of about $rowCount';

语言对应的日期格式和符号需要一并指定。在源码中，它们会以下列形式进行定义：

The date patterns and symbols of the locale will also need to be specified. In the source code, the date patterns and symbols are defined like this:

const nnLocaleDatePatterns = {
  'd': 'd.',
  'E': 'ccc',
  'EEEE': 'cccc',
  'LLL': 'LLL',
  // ...
}

const nnDateSymbols = {
  'NAME': 'nn',
  'ERAS': <dynamic>[
    'f.Kr.',
    'e.Kr.',
  ],
  // ...
}

上列内容需要修改以匹配语言的正确日期格式。可惜的是，intl 并不具备数字格式的灵活性，以至于 _NnMaterialLocalizationsDelegate 需要使用现有的语言的格式作为替代方法：

These will need to be modified for the locale to use the correct date formatting. Unfortunately, since the intl library does not share the same flexibility for number formatting, the formatting for an existing locale will have to be used as a substitute in _NnMaterialLocalizationsDelegate:

class _NnMaterialLocalizationsDelegate
    extends LocalizationsDelegate<MaterialLocalizations> {
  const _NnMaterialLocalizationsDelegate();

  @override
  bool isSupported(Locale locale) => locale.languageCode == 'nn';

  @override
  Future<MaterialLocalizations> load(Locale locale) async {
    final String localeName = intl.Intl.canonicalizedLocale(locale.toString());

    // The locale (in this case `nn`) needs to be initialized into the custom
    // date symbols and patterns setup that Flutter uses.
    date_symbol_data_custom.initializeDateFormattingCustom(
      locale: localeName,
      patterns: nnLocaleDatePatterns,
      symbols: intl.DateSymbols.deserializeFromMap(nnDateSymbols),
    );

    return SynchronousFuture<MaterialLocalizations>(
      NnMaterialLocalizations(
        localeName: localeName,
        // The `intl` library's NumberFormat class is generated from CLDR data
        // (see https://github.com/dart-lang/intl/blob/master/lib/number_symbols_data.dart).
        // Unfortunately, there is no way to use a locale that isn't defined in
        // this map and the only way to work around this is to use a listed
        // locale's NumberFormat symbols. So, here we use the number formats
        // for 'en_US' instead.
        decimalFormat: intl.NumberFormat('#,##0.###', 'en_US'),
        twoDigitZeroPaddedFormat: intl.NumberFormat('00', 'en_US'),
        // DateFormat here will use the symbols and patterns provided in the
        // `date_symbol_data_custom.initializeDateFormattingCustom` call above.
        // However, an alternative is to simply use a supported locale's
        // DateFormat symbols, similar to NumberFormat above.
        fullYearFormat: intl.DateFormat('y', localeName),
        compactDateFormat: intl.DateFormat('yMd', localeName),
        shortDateFormat: intl.DateFormat('yMMMd', localeName),
        mediumDateFormat: intl.DateFormat('EEE, MMM d', localeName),
        longDateFormat: intl.DateFormat('EEEE, MMMM d, y', localeName),
        yearMonthFormat: intl.DateFormat('MMMM y', localeName),
        shortMonthDayFormat: intl.DateFormat('MMM d'),
      ),
    );
  }

  @override
  bool shouldReload(_NnMaterialLocalizationsDelegate old) => false;
}

需要了解更多关于本地化字符串的内容，可以查看 flutter_localizations README。

For more information about localization strings, see the flutter_localizations README.

一旦你实现了指定语言的 GlobalMaterialLocalizations 和 LocalizationsDelegate 的子类，你只需要给你的 app 添加此语言以及一个 delegate 的实例。这里有一些代码展示了如何设置 app 的语言为尼诺斯克语以及如何给 app 的 localizationsDelegates 列表添加 NnMaterialLocalizations delegate 实例。

Once you’ve implemented your language-specific subclasses of GlobalMaterialLocalizations and LocalizationsDelegate, you just need to add the language and a delegate instance to your app. Here’s some code that sets the app’s language to Nynorsk and adds the NnMaterialLocalizations delegate instance to the app’s localizationsDelegates list:

const MaterialApp(
  localizationsDelegates: [
    GlobalWidgetsLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    NnMaterialLocalizations.delegate, // Add the newly created delegate
  ],
  supportedLocales: [
    Locale('en', 'US'),
    Locale('nn'),
  ],
  home: Home(),
),

其他的国际化方法

Alternative internationalization workflows

本节主要介绍国际化 Flutter 应用的不同方法。

This section describes different approaches to internationalize your Flutter application.

应用程序本地化资源的替代类

An alternative class for the app’s localized resources

之前的示例应用主要根据 Dart intl package 定义，为了简单起见，或者可能想要与不同的 i18n 框架集成，开发者也可以选择自己的方法来管理本地化的值。

The previous example was defined in terms of the Dart intl package. Developers can choose their own approach for managing localized values for the sake of simplicity or perhaps to integrate with a different i18n framework.

点击查看 minimal 应用的完整源代码。

Complete source code for the minimal app.

在下面这个样例中，包含应用本地化版本的类 DemoLocalizations 直接在每种语言的 Map 中包括了所有的翻译。

In the below example, the DemoLocalizations class includes all of its translations directly in per language Maps.

class DemoLocalizations {
  DemoLocalizations(this.locale);

  final Locale locale;

  static DemoLocalizations of(BuildContext context) {
    return Localizations.of<DemoLocalizations>(context, DemoLocalizations)!;
  }

  static const _localizedValues = <String, Map<String, String>>{
    'en': {
      'title': 'Hello World',
    },
    'es': {
      'title': 'Hola Mundo',
    },
  };

  static List<String> languages ()=> _localizedValues.keys.toList();

  String get title {
    return _localizedValues[locale.languageCode]!['title']!;
  }
}

在 minimal 应用中，DemoLocalizationsDelegate 略有不同，它的 load 方法返回一个 SynchronousFuture，因为不需要进行异步加载。

In the minimal app the DemoLocalizationsDelegate is slightly different. Its load method returns a SynchronousFuture because no asynchronous loading needs to take place.

class DemoLocalizationsDelegate
    extends LocalizationsDelegate<DemoLocalizations> {
  const DemoLocalizationsDelegate();

  @override
  bool isSupported(Locale locale) => DemoLocalizations.languages().contains(locale.languageCode);


  @override
  Future<DemoLocalizations> load(Locale locale) {
    // Returning a SynchronousFuture here because an async "load" operation
    // isn't needed to produce an instance of DemoLocalizations.
    return SynchronousFuture<DemoLocalizations>(DemoLocalizations(locale));
  }

  @override
  bool shouldReload(DemoLocalizationsDelegate old) => false;
}

附录：使用 Dart intl 工具

Using the Dart intl tools

在你使用 Dart intl package 进行构建 API 之前，你应该想要了解一下 intl package 的文档。

Before building an API using the Dart intl package you’ll want to review the intl package’s documentation. Here’s a summary of the process for localizing an app that depends on the intl package.

这个 demo app 依赖于一个生成的源文件，叫做 l10n/messages_all.dart，这个文件定义了 app 使用的所有本地化的字符串。

The demo app depends on a generated source file called l10n/messages_all.dart, which defines all of the localizable strings used by the app.

重建 l10n/messages_all.dart 需要 2 步。

Rebuilding l10n/messages_all.dart requires two steps.

在 app 的根目录，使用 lib/main.dart 生成 l10n/intl_messages.arb：
With the app’s root directory as the current directory, generate l10n/intl_messages.arb from lib/main.dart:
```
$ flutter pub run intl_translation:extract_to_arb --output-dir=lib/l10n lib/main.dart
```
intl_messages.arb 是一个 JSON 格式的文件，每一个入口代表定义在 main.dart 里面的 Intl.message() 方法。 intl_en.arb 和 intl_es.arb 分别作为英语和西班牙语翻译的模板。这些翻译是由你（开发者）来创建的。
The intl_messages.arb file is a JSON format map with one entry for each Intl.message() function defined in main.dart. This file serves as a template for the English and Spanish translations, intl_en.arb and intl_es.arb. These translations are created by you, the developer.
在 app 的根目录，生成每个 intl_<locale>.arb 文件对应的 intl_messages_<locale>.dart 文件，以及 intl_messages_all.dart 文件，它引入了所有的信息文件。
With the app’s root directory as the current directory, generate intl_messages_<locale>.dart for each intl_<locale>.arb file and intl_messages_all.dart, which imports all of the messages files:
```
$ flutter pub run intl_translation:generate_from_arb \
 --output-dir=lib/l10n --no-use-deferred-loading \
 lib/main.dart lib/l10n/intl_*.arb
```
Windows 系统不支持文件名通配符。列出的 .arb 文件是由 intl_translation:extract_to_arb 命令生成的。
Windows does not support file name wildcarding. Instead, list the .arb files that were generated by the intl_translation:extract_to_arb command.
```
$ flutter pub run intl_translation:generate_from_arb \
 --output-dir=lib/l10n --no-use-deferred-loading \
 lib/main.dart \
 lib/l10n/intl_en.arb lib/l10n/intl_fr.arb lib/l10n/intl_messages.arb
```
DemoLocalizations 类使用生成的 initializeMessages() 方法（该方法定义在 intl_messages_all.dart 文件）来加载本地化的信息，然后使用 Intl.message() 来查阅这些本地化的信息。
The DemoLocalizations class uses the generated initializeMessages() function (defined in intl_messages_all.dart) to load the localized messages and Intl.message() to look them up.

已支持的平台

已支持的平台
Supported platforms
我们如何定义一个已支持的平台
How we define a supported platform

已支持的平台

Supported platforms

2.5 版本之后，Flutter 支持以下平台：

As of release 2.5, Flutter supports the following platforms:

平台 Platform	版本 Version	渠道 Channels
Android	API 19 及以上 API 19 & above	全部 All
iOS	iOS 9 及以上 iOS 9 & above	全部 All
Linux	Debian 10 及以上 Debian 10 & above	全部 All
macOS	El Capitan 及以上 El Capitan & above	全部 All
Web	Chrome 84 及以上 Chrome 84 & above	全部 All
Web	Firefox 72.0 及以上 Firefox 72.0 & above	全部 All
Web	Safari on El Capitan 及以上 Safari on El Capitan & above	全部 All
Web	Edge 1.2.0 及以上 Edge 1.2.0 & above	全部 All
Windows	Windows 7 及以上 Windows 7 & above	全部 All

平台

Platform

版本

Version

渠道

Channels

Android

API 19 及以上

API 19 & above

全部

All

iOS

iOS 9 及以上

iOS 9 & above

全部

All

Linux

Debian 10 及以上

Debian 10 & above

全部

All

macOS

El Capitan 及以上

El Capitan & above

全部

All

Web

Chrome 84 及以上

Chrome 84 & above

全部

All

Web

Firefox 72.0 及以上

Firefox 72.0 & above

全部

All

Web

Safari on El Capitan 及以上

Safari on El Capitan & above

全部

All

Web

Edge 1.2.0 及以上

Edge 1.2.0 & above

全部

All

Windows

Windows 7 及以上

Windows 7 & above

全部

All

我们如何定义一个已支持的平台

How we define a supported platform

从 Flutter 1.20 开始，我们为 Flutter 运行的平台定义了三层支撑：

As of Flutter 1.20, we define three tiers of support for the platforms on which Flutter runs:

支持谷歌测试平台，这些平台是谷歌 Flutter 团队在每次提交时集成测试的平台。对于这些平台，在从 master 分支合并到 dev 通道之前，我们还会运行提交测试。
Supported Google-tested platforms, which are platforms the Flutter team at Google tests in continuous integration at every commit. For these platforms, we also run post-commit tests before rolling from the master channel to the dev channel.
由社区测试尽力支持的平台，我们相信这些平台是通过编码实践和特别测试支持的，但依赖社区进行测试。
Best effort platforms, supported community testing, which are platforms we believe we support through coding practices and ad-hoc testing, but rely on the community for testing.
不受支持的平台，这些平台可以工作，但开发团队不直接测试或支持。
Unsupported platforms, which are platforms that may work, but that the development team does not directly test or support.

支持谷歌测试的平台

Supported Google-tested platforms

平台 Platform	版本 Version
Android	Android SDK 30
Android	Android SDK 29
Android	Android SDK 28
Android	Android SDK 27
Android	Android SDK 26
Android	Android SDK 25
Android	Android SDK 24
Android	Android SDK 23
Android	Android SDK 22
Android	Android SDK 21
Android	Android SDK 19
iOS	14 (all)
iOS	13.3-13.7
iOS	13.0
iOS	12.4 & 12.4.1
iOS	9.3.6
Web	Chrome 84
Web	Firefox 72.0
Web	Safari / Catalina
Web	Edge 1.2.0
Windows	Windows 10
macOS	El Capitan & greater
Linux	Debian 10

请注意，Android SDK 19 的测试涵盖 Android SDK 20，因为两个版本之间的差异很小。

Note that Android SDK 20 is covered by testing Android SDK 19, as the differences between the two platform versions are minimal.

社区测试尽力支持的平台

Best effort platforms tested by the community

平台 Platform	版本 Version
Android	Android SDK 22
Android	Android SDK 20
Android	Android SDK 19
Android	Android SDK 18
Android	Android SDK 17
Android	Android SDK 16
iOS	iOS 13.1
iOS	iOS 12.1-12.3
iOS	iOS 10 (all)
iOS	iOS 9.0
Windows	Windows 8
Windows	Windows 7
Linux	Debian & below

我们已经放弃对 iOS 8 的支持。更多信息，请参阅 go/rfc-ios8-deprecation。

We have dropped iOS8 support. For more information, see go/rfc-ios8-deprecation for details.

不受支持的平台

Unsupported platforms

平台 Platform	版本 Version
Android	Android SDK 15 及以上 Android SDK 15 & below
iOS	iOS 8 及以上 iOS 8 & below
Windows	Windows Vista 及以上 Windows Vista & below
Windows	任何 32 位平台 Any 32-bit platform
macOS	Yosemite 及以上 Yosemite & below

平台

Platform

版本

Version

Android

Android SDK 15 及以上

Android SDK 15 & below

iOS

iOS 8 及以上

iOS 8 & below

Windows

Windows Vista 及以上

Windows Vista & below

Windows

任何 32 位平台

Any 32-bit platform

macOS

Yosemite 及以上

Yosemite & below

添加 iOS App Clip target

步骤 1 - 打开项目
Step 1 - Open project
步骤 2 - 添加一个 App Clip 的 target
Step 2 - Add an App Clip target
步骤 3 - 移除不需要的文件
Step 3 - Remove unneeded files
步骤 4 - 共享构建配置
Step 4 - Share build configurations
步骤 5 - 共享代码和资源
Step 5 - Share code and assets
- 选项 1 - 共享所有东西
  Option 1 - Share everything
- 选项 2 - 为 App Clip 自定义 Flutter 的启动器
  Option 2 - Customize Flutter launch for App Clip
步骤 6 - 添加 App Clip 的关联域名
Step 6 - Add App Clip associated domains
步骤 7 - 整合 Flutter
Step 7 - Integrate Flutter
Step 8 - Disable Bitcode
Step 9 - 整合插件
Step 9 - Integrate plugins
运行
Run
调试和热重载
Debugging, hot reload

这个指南介绍了如何手动添加另一个使用 Flutter 来渲染的 iOS App Clip target, 并将它集成到您现有的 Flutter 项目或 add-to-app 项目。

This guide describes how to manually add another Flutter-rendering iOS App Clip target to your existing Flutter project or add-to-app project.

如果您有兴趣将 App Clip 自动集成到 iOS 应用中，请参阅功能请求 #65451.

If you are interested in automatically integrating an App Clip into your iOS app, see feature request #65451.

要查看完整可用的示例，请参阅 GitHub 上的 App Clip 示例。

To see a working sample, see the App Clip sample on GitHub.

步骤 1 - 打开项目

Step 1 - Open project

打开您的 iOS Xcode 工程，例如您的纯 Flutter 项目中的 ios/Runner.xcworkspace。

Open your iOS Xcode project, such as ios/Runner.xcworkspace for full-Flutter apps.

步骤 2 - 添加一个 App Clip 的 target

Step 2 - Add an App Clip target

2.1

点击您项目的 Project Navigator 来显示工程设置。

Click on your project in the Project Navigator to show the project settings.

点击 target 列表底部的 + 来添加一个新的 target。

Press + at the bottom of the target list to add a new target.

2.2

为您的新 target 选择 App Clip 类型。

Select the App Clip type for your new target.

2.3

在对话框为您的新 target 输入详情。

Enter your new target detail in the dialog.

选择 Storyboard 作为界面。

Select Storyboard for Interface.

选择 UIKit App Delegate 作为生命周期。

Select UIKit App Delegate for Life Cycle.

选择与您原来的 target 相同的编程语言。

Select the same language as your original target for Language.

(换句话说，请勿为 Objective-C target 创建 Swift 类型的 App Clip target，反之亦然，以简化设置。)

(In other words, don’t create a Swift App Clip target for an Objective-C main target, and vice versa to simplify the setup.)

2.4

在接下来的对话框中，为新的 target 激活 (activate) 一个新的 scheme。

In the following dialog, activate the new scheme for the new target.

步骤 3 - 移除不需要的文件

Step 3 - Remove unneeded files

3.1

在项目 Project Navigator 的新创建的 App Clip 组中，将除了 Info.plist 和 App Clip target.entitlements 以外的所有内容删除。

In the Project Navigator, in the newly created App Clip group, delete everything except Info.plist and <app clip target>.entitlements.

移动文件到废纸篓。

Move files to trash.

3.2

如果您不使用 SceneDelegate.swift 文件，移除在 Info.plist 中对应的引用。

If you don’t use the SceneDelegate.swift file, remove the reference to it in the Info.plist.

打开 App Clip 组中的 Info.plist。删除 Application Scene Manifest 字典条目。

Open the Info.plist file in the App Clip group. Delete the entire dictionary entry for Application Scene Manifest.

Step 4 - Share build configurations

对于 add-to-app 项目，此步骤不是必需的，因为 add-to-app 有自己的自定义构建配置和版本。

This step isn’t necessary for add-to-app projects since add-to-app projects have their custom build configurations and versions.

4.1

返回项目设置，现在选择 Project 条目，而不是 Targets 里的任何 target。

Back in the project settings, select the project entry now rather than any targets.

在 Info 选项卡页中的 Configurations 可扩展组下，展开 Debug、Profile 和 Release 条目。

In the Info tab, under the Configurations expandable group, expand the Debug, Profile, and Release entries.

每一个 App Clip target 的下拉菜单的值都应该与常规应用 target 中的值相同。

For each, select the same value from the drop-down menu for the App Clip target as the entry selected for the normal app target.

这使您的 App Clip target 可以访问 Flutter 的必需构建设置。

This gives your App Clip target access to Flutter’s required build settings.

4.2

在 App Clip 组的 Info.plist 文件中，设置：

In the App Clip group’s Info.plist file, set:

Build version string (short) to $(FLUTTER_BUILD_NAME)
Bundle version to $(FLUTTER_BUILD_NUMBER)

Step 5 - Share code and assets

Option 1 - Share everything

假设您的目标是在 App Clip 中显示与普通应用相同的 Flutter UI，并共享相同的代码和资源。

Assuming the intent is to show the same Flutter UI in the standard app as in the App Clip, share the same code and assets.

对于以下每一个文件： Main.storyboard、 Assets.xcassets、 LaunchScreen.storyboard、GeneratedPluginRegistrant.m 和 AppDelegate.swift，（如果您是 Objective-C 还应该包括 Supporting Files/main.m）选择文件并且在检查器中选择第一个选项卡，并且在 Target Membership 选中 App Clip。

For each of the following: Main.storyboard, Assets.xcassets, LaunchScreen.storyboard, GeneratedPluginRegistrant.m, and AppDelegate.swift (and Supporting Files/main.m if using Objective-C), select the file, then in the first tab of the inspector, also include the App Clip target in the Target Membership checkbox group.

选项 2 - 为 App Clip 自定义 Flutter 的启动器

Option 2 - Customize Flutter launch for App Clip

在这个例子中，不需要删除在步骤 3 中的任何东西。相对的，使用 iOS add-to-app APIs 的模板来自定义 Flutter 启动器。可以参考示例自定义 Flutter 路由。

In this case, do not delete everything listed in Step 3. Instead, use the scaffolding and the iOS add-to-app APIs to perform a custom launch of Flutter. For example to show a custom Flutter route.

步骤 6 - 添加 App Clip 的关联域名

Step 6 - Add App Clip associated domains

这是一个 App Clip 开发的标准步骤。请查看苹果官方文档。

This is a standard step for App Clip development. See the official Apple documentation.

6.1

打开 <app clip target>.entitlements 文件。添加 Associated Domains 数组。添加一行 appclips:<your bundle id> 到数组中。

Open the <app clip target>.entitlements file. Add an Associated Domains Array type. Add a row to the array with appclips:<your bundle id>.

6.2

同样的相关域名权利也需要添加到您的主应用程序中。

The same associated domains entitlement needs to be added to your main app as well.

将 <app clip target>.entitlements 文件从 App Clip 组复制到主应用程序组，并将其重命名为与主目标相同的名称，例如 Runner.entitlements。

Copy the <app clip target>.entitlements file from your App Clip group to your main app group and rename it to the same name as your main target such as Runner.entitlements.

打开文件并删除主应用程序授权文件的 Parent Application Identifiers 条目（将该条目保留为 App Clip 的授权文件）。

Open the file and delete the Parent Application Identifiers entry for the main app’s entitlement file (leave that entry for the App Clip’s entitlement file).

6.3

返回项目设置，选择主应用 target，打开 Build Settings 选项卡。设置 Code Signing Entitlements 的值为主应用创建的第二个授权文件的相对路径。

Back in the project settings, select the main app’s target, open the Build Settings tab. Set the Code Signing Entitlements setting to the relative path of the second entitlements file created for the main app.

步骤 7 - 整合 Flutter

Step 7 - Integrate Flutter

add-to-app 不需要这些步骤。

These steps are not necessary for add-to-app.

7.1

在您的 App Clip 的 target 的项目设置，打开 Build Settings 选项卡。

In your App Clip’s target’s project settings, open the Build Settings tab.

为 Framework Search Paths 添加两个内容：

For setting Framework Search Paths, add 2 entries:

$(inherited)
$(PROJECT_DIR)/Flutter

换句话说，与主应用程序 target 的构建设置相同。

In other words, the same as the main app target’s build settings.

7.2

如果是 Swift target，设置 Objective-C Bridging Header 构建配置为 Runner/Runner-Bridging-Header.h。

For Swift target, set the Objective-C Bridging Header build setting to Runner/Runner-Bridging-Header.h

换句话说，与主应用程序 target 的构建设置相同。

In other words, the same as the main app target’s build settings.

7.3

现在打开 Build Phases 选项卡。点击 + 并且选择 New Run Script Phase。

Now open the Build Phases tab. Press the + sign and select New Run Script Phase.

拖动新的 phase 到 Dependencies phase。

Drag that new phase to below the Dependencies phase.

展开新 phase 并将以下内容添加到脚本：

Expand the new phase and add this line to the script content:

/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" build

简单来说，与主应用程序 target 的构建设置相同。

In other words, the same as the main app target’s build phases.

这可以确保在运行 App Clip target 时编译 Flutter 的 Dart 代码。

This ensures that your Flutter Dart code is compiled when running the App Clip target.

7.4

再次点击 + 并且选择 New Run Script Phase。这是最后一个 phase。

Press the + sign and select New Run Script Phase again. Leave it as the last phase.

这次添加如下内容：

This time, add:

/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" embed_and_thin

简单来说，与主应用程序 target 的构建设置相同。

In other words, the same as the main app target’s build phases.

这将确保您的 Flutter 应用程序和引擎嵌入到 App Clip bundle 中。

This ensures that your Flutter app and engine are embedded into the App Clip bundle.

Step 8 - Disable Bitcode

在 App Clip target 的 Build Settings 选项卡中，将 Enable Bitcode 设置设置为 No。

In the App Clip target’s Build Settings tab, set the Enable Bitcode setting to No.

Step 9 - 整合插件

Step 9 - Integrate plugins

9.1

在您的 Flutter 项目或是 add-to-app 的宿主项目中打开 Podfile 文件。

Open the Podfile for your Flutter project or add-to-app host project.

如果是完整的 Flutter 项目，替换下面这段代码：

For full-Flutter apps, replace the following section:

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

为：

with:

use_frameworks!
use_modular_headers!
flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))

target 'Runner'
target '<name of your App Clip target>'

在文件的开始，需要把 platform :ios, '9.0' 的注释解除，并且为您的 2 个 target 设置最低可运行的 iOS 系统版本。

At the top of the file, also uncomment platform :ios, '9.0' and set the version to the lowest of the 2 target’s iOS Deployment Target.

如果是 add-to-app，紧跟下面的代码：

For add-to-app, add to:

target 'MyApp' do
  install_all_flutter_pods(flutter_application_path)
end

添加：

with:

target 'MyApp' do
  install_all_flutter_pods(flutter_application_path)
end

target '<name of your App Clip target>'
  install_all_flutter_pods(flutter_application_path)
end

9.2

在命令行中，目前工作目录需要是您的 Flutter 项目目录。

From the command line, enter your Flutter project directory.

cd ios

然后运行

then

pod install.

运行

Run

您现在可以在 Xcode 的 scheme 下拉中选择并运行您的 App Clip target 了，选择一个 iOS 14 的设备并点击运行。

You can now run your App Clip target from Xcode by selecting your App Clip target from the scheme drop-down, selecting an iOS 14 device and pressing run.

要从头测试 App Clip 的启动，您也可以查看苹果公司的文档测试您的 App Clip 的启动体验。

To test launching an App Clip from the beginning, also consult Apple’s doc on Testing Your App Clip’s Launch Experience.

调试和热重载

Debugging, hot reload

不幸的是，由于网络权限的原因，flutter attach 无法在 App clip 中自动发现 Flutter 会话。

Unfortunately flutter attach cannot auto-discover the Flutter session in an App Clip due to networking permission restrictions.

为了调试 App clip 并使用诸如热重新加载之类的功能，必须在运行应用后从 Xcode 中的控制台输出中查找 Observatory URI。

In order to debug your App Clip and use functionalities like hot reload, you must look for the Observatory URI from the console output in Xcode after running.

您需要复制粘贴它们到 flutter attach 来连接。

You must then copy paste it back into the flutter attach command to connect.

例如：

For example:

flutter attach --debug-uri <copied URI>

作为 Apple Watch 插件

步骤 1: 在 Xcode 中开启 bitcode
Step 1: Enable bitcode in Xcode
步骤 2: 添加一个 Apple Watch target
Step 2: Add an Apple Watch target

虽然您不能使用 Flutter 构建 Apple Watch 应用程序，但可以向 Flutter 应用程序添加 Apple Watch 的本地扩展。

While you cannot build an Apple Watch app with Flutter, it is possible to add a native Apple Watch extension to a Flutter app.

步骤 1: 在 Xcode 中开启 bitcode

Step 1: Enable bitcode in Xcode

Apple Watch target 要求启用 bitcode，因此请按照创建支持 bitcode 的 iOS 应用程序中的步骤在您的应用程序中使用 bitcode。

Apple Watch targets require bitcode to be enabled, so follow the steps in Creating an iOS Bitcode enabled app to use bitcode in your app.

步骤 2: 添加一个 Apple Watch target

Step 2: Add an Apple Watch target

在菜单中，选择 File > New > Target。当对话框打开后，在顶部选择 watchOS 并且点击 Watch App for iOS App。然后，点击 Next，输入产品名，最后选择 Enter。

In the menu, select File > New > Target. Once the dialog opens, select watchOS at the top and click Watch App for iOS App. Click Next, enter a product name, and select Enter.

Adding an Apple Watch target

使用 dart:ffi 调用本地代码

动态链接 vs 静态链接
Dynamic vs static linking
步骤 1：创建插件
Step 1: Create a plugin
步骤 2：添加 C/C++ 源码
Step 2: Add C/C++ sources
步骤 3：在 FFI 库中读取代码
Step 3: Load the code using the FFI library
其他的用例
Other use cases
FAQ
- Android APK 尺寸（共享对象压缩）
  Android APK size (shared object compression)
- 删除的 iOS 符号
  iOS symbols stripped

Flutter 移动版可以使用 dart:ffi 库来调用本地的 C API。 FFI 代表 外部功能接口。类似功能的其他术语包括本地接口和语言绑定。

Flutter mobile can use the dart:ffi library to call native C APIs. FFI stands for foreign function interface. Other terms for similar functionality include native interface and language bindings.

您必须首先确保本地代码已加载，并且其符号对 Dart 可见，然后才能在库或程序使用 FFI 库绑定本地代码。本页主要介绍如何在 Flutter 插件或应用程序中编译、打包和加载本地代码。

Before your library or program can use the FFI library to bind to native code, you must ensure that the native code is loaded and its symbols are visible to Dart. This page focuses on compiling, packaging, and loading native code within a Flutter plugin or app.

本教程演示了如何在 Flutter 插件中捆绑 C/C++ 源代码，并使用 Android 和 iOS 上的 Dart FFI 库绑定它们。在本示例中，您将创建一个实现 32 位的加法 C 函数，然后通过名为 “native_add” 的 Dart 插件暴露它。

This tutorial demonstrates how to bundle C/C++ sources in a Flutter plugin and bind to them using the Dart FFI library on both Android and iOS. In this walkthrough, you’ll create a C function that implements 32-bit addition and then exposes it through a Dart plugin named “native_add”.

动态链接 vs 静态链接

Dynamic vs static linking

本地库可以动态或静态地链接到应用程序中。一个静态链接库会被嵌入到应用程序的可执行映像中，并在应用程序启动时加载。

A native library can be linked into an app either dynamically or statically. A statically linked library is embedded into the app’s executable image, and is loaded when the app starts.

静态链接中的符号可以使用 DynamicLibrary.executable 或 DynamicLibrary.process 来加载.

Symbols from a statically linked library can be loaded using DynamicLibrary.executable or DynamicLibrary.process.

相比之下，动态链接库则分布在应用程序中的单独的文件或文件夹中，并按需加载。在 Android 上，动态链接库作为一组 .so（ELF 可执行与可链接格式）文件分发，每个架构各有一个。在 iOS 上，它是作为 .framework 文件夹分发的。

A dynamically linked library, by contrast, is distributed in a separate file or folder within the app, and loaded on-demand. On Android, a dynamically linked library is distributed as a set of .so (ELF) files, one for each architecture. On iOS, it’s distributed as a .framework folder.

动态链接库在 Dart 中可以通过 DynamicLibrary.open 加载。

A dynamically linked library can be loaded into Dart via DynamicLibrary.open.

Dart dev 频道中的 API 已经可用： Dart API 参考文档.

API documentation is available from the Dart dev channel: Dart API reference documentation.

步骤 1：创建插件

Step 1: Create a plugin

如果您已经有一个插件，跳过这步。

If you already have a plugin, skip this step.

如果要创建一个名为 “native_add” 的插件，您需要这么做：

To create a plugin called “native_add”, do the following:

$ flutter create --platforms=android,ios --template=plugin native_add
$ cd native_add

步骤 2：添加 C/C++ 源码

Step 2: Add C/C++ sources

您需要让 Android 和 iOS 构建系统知道本地代码的存在，以便代码可以被编译并链接到最终的应用程序中。

You need to inform both the Android and iOS build systems about the native code so the code can be compiled and linked appropriately into the final application.

您可以将源代码添加到 ios 文件夹，因为 CocoaPods 不允许源码处于比 podspec 文件更高的目录层级，但是 Gradle 允许您指向 ios 文件夹。 iOS 和 Android 不需要使用相同的源代码；当然，您也可以将特定于 Android 的源代码添加到 android 文件夹并修改 CMakeLists.txt 文件。

You add the sources to the ios folder, because CocoaPods doesn’t allow including sources above the podspec file, but Gradle allows you to point to the ios folder. It’s not required to use the same sources for both iOS and Android; you may, of course, add Android-specific sources to the android folder and modify CMakeLists.txt appropriately.

FFI 库只能与 C 符号绑定，因此在 C++ 中，这些符号添加 extern C 标记。还应该添加属性来表明符号是需要被 Dart 引用的，以防止链接器在优化链接时会丢弃符号。

The FFI library can only bind against C symbols, so in C++ these symbols must be marked extern C. You should also add attributes to indicate that the symbols are referenced from Dart, to prevent the linker from discarding the symbols during link-time optimization.

作为示例，创建一个 C++ 文件，路径为：ios/Classes/native_add.cpp。（请注意，模板已经为您创建了此文件。）在项目的根目录下中执行以下命令：

For example, to create a C++ file named ios/Classes/native_add.cpp, use the following instructions. (Note that the template has already created this file for you.) Start from the root directory of your project:

cat > ios/Classes/native_add.cpp << EOF
#include <stdint.h>

extern "C" __attribute__((visibility("default"))) __attribute__((used))
int32_t native_add(int32_t x, int32_t y) {
    return x + y;
}
EOF

在 iOS 中，您需要告诉 Xcode 如何静态链接这个文件：

On iOS, you need to tell Xcode to statically link the file:

在 Xcode 中，打开 Runner.xcworkspace。
In Xcode, open Runner.xcworkspace.
添加 C/C++/Objective-C/Swift 源码文件到 Xcode 工程中。
Add the C/C++/Objective-C/Swift source files to the Xcode project.

在 Android 中，您需要创建一个 CMakeLists.txt 文件用来定义如何编译源文件，同时告诉 Gradle 如何去定位它们。在项目根目录下，运行如下代码：

On Android, you need to create a CMakeLists.txt file to define how the sources should be compiled and point Gradle to it. From the root of your project directory, use the following instructions

cat > android/CMakeLists.txt << EOF
cmake_minimum_required(VERSION 3.4.1)  # for example

add_library( native_add

             # Sets the library as a shared library.
             SHARED

             # Provides a relative path to your source file(s).
             ../ios/Classes/native_add.cpp )
EOF

最后，添加一个 externalNativeBuild 到您的 android/build.gradle 文件中。示例如下：

Finally, add an externalNativeBuild section to android/build.gradle. For example:

android {
  // ...
  externalNativeBuild {
    // Encapsulates your CMake build configurations.
    cmake {
      // Provides a relative path to your CMake build script.
      path "CMakeLists.txt"
    }
  }
  // ...
}

步骤 3：在 FFI 库中读取代码

Step 3: Load the code using the FFI library

在示例中，您需要添加如下的代码到 lib/native_add.dart。但是，Dart 在何处进行代码绑定并不重要。

In this example, you can add the following code to lib/native_add.dart. However the location of the Dart binding code is not important.

首先，您需要创建一个 DynamicLibrary 来处理本地代码。这一步在 iOS 和 Android 之间有所不同：

First, you must create a DynamicLibrary handle to the native code. This step varies between iOS and Android:

import 'dart:ffi'; // For FFI
import 'dart:io'; // For Platform.isX

final DynamicLibrary nativeAddLib = Platform.isAndroid
    ? DynamicLibrary.open('libnative_add.so')
    : DynamicLibrary.process();

请注意，在 Android 上，本地库的名称是定义在 CMakeLists.txt 中的（见上文），但在 iOS 上，它将使用插件的名称。

Note that on Android the native library is named in CMakeLists.txt (see above), but on iOS it takes the plugin’s name.

您可以通过使用库的句柄来解析 native_add 符号：

With a handle to the enclosing library, you can resolve the native_add symbol:

final int Function(int x, int y) nativeAdd = nativeAddLib
    .lookup<NativeFunction<Int32 Function(Int32, Int32)>>('native_add')
    .asFunction();

现在，您可以调用它了。在自动生成的 example 项目（example/lib/main.dart）中演示它。

Finally, you can call it. To demonstrate this within the auto-generated “example” app (example/lib/main.dart):

// Inside of _MyAppState.build:
        body: Center(
          child: Text('1 + 2 == ${nativeAdd(1, 2)}'),
        ),

其他的用例

Other use cases

iOS 和 macOS

iOS and macOS

动态链接库在应用程序启动时由动态链接器自动加载。它们的组成符号可以用 DynamicLibrary.process。您还可以使用 DynamicLibrary.open 来限制符号解析的范围，但目前仍然不确定苹果的审查程序将如何处理两者的使用。

Dynamically linked libraries are automatically loaded by the dynamic linker when the app starts. Their constituent symbols can be resolved using DynamicLibrary.process. You can also get a handle to the library with DynamicLibrary.open to restrict the scope of symbol resolution, but it’s unclear how Apple’s review process handles this.

您可以使用 DynamicLibrary.executable 或 DynamicLibrary.process 解析静态链接到应用程序二进制文件的符号。

Symbols statically linked into the application binary can be resolved using DynamicLibrary.executable or DynamicLibrary.process.

平台库

Platform library

要链接到平台库，请按照如下说明：

To link against a platform library, use the following instructions:

在 Xcode 中，打开 Runner.xcworkspace。
In Xcode, open Runner.xcworkspace.
选择目标设备。
Select the target platform.
在 Linked Frameworks and Libraries 中点击 +。
Click + in the Linked Frameworks and Libraries section.
选择要链接的系统库。
Select the system library to link against.

第一方库

First-party library

第一方本地库可以作为源文件或（已签名的）.framework 文件被包含在内。它也可能包括静态链接的档案，但需要测试。

A first-party native library can be included either as source or as a (signed) .framework file. It’s probably possible to include statically linked archives as well, but it requires testing.

源码

Source code

要直接链接到源代码，请按照如下说明：

To link directly to source code, use the following instructions:

在 Xcode 中，打开 Runner.xcworkspace。
In Xcode, open Runner.xcworkspace.
添加 C/C++/Objective-C/Swift 源码到 Xcode 工程中。
Add the C/C++/Objective-C/Swift source files to the Xcode project.
将以下前缀添加到导出的符号声明中，以确保它们对 Dart 可见：
Add the following prefix to the exported symbol declarations to ensure they are visible to Dart:

C/C++/Objective-C
```
extern "C" /* <= C++ only */ __attribute__((visibility("default"))) __attribute__((used))
```
Swift
```
@_cdecl("myFunctionName")
```

已编译的动态库

Compiled (dynamic) library

要链接到已编译过的动态库，请按照如下说明：

To link to a compiled dynamic library, use the following instructions:

如果存在已进行签名的 Framework 文件，请打开 Runner.xcworkspace。
If a properly signed Framework file is present, open Runner.xcworkspace.
添加 framework 文件到 Embedded Binaries 区域中。
Add the framework file to the Embedded Binaries section.
同时将其添加到 Xcode 中目标的 Linked Frameworks & Libraries 部分。
Also add it to the Linked Frameworks & Libraries section of the target in Xcode.

已编译的（动态）库 (macOS)

Compiled (dynamic) library (macOS)

要添加一个闭源的库到 Flutter macOS 桌面应用，请按照如下说明：

To create add a closed source library to a Flutter macOS Desktop app, use the following instructions.

按照 Flutter 桌面的使用说明来创建 Flutter 桌面应用程序。
Follow the instructions for Flutter desktop to create a Flutter desktop app.
在 Xcode 中打开 yourapp/macos/Runner.xcworkspace。
Open the yourapp/macos/Runner.xcworkspace in Xcode.
1. 拖动您已经预编译的 libyourlibrary.dylib 到您的 Runner/Frameworks。
  Drag your precompiled library (libyourlibrary.dylib) into Runner/Frameworks.
2. 点击 Runner 然后进入 Build Phases 标签.
  Click Runner and go to the Build Phases tab.
  1. 拖动 libyourlibrary.dylib 到 Copy Bundle Resources 列表。
    Drag libyourlibrary.dylib into the Copy Bundle Resources list.
  2. 在 Embed Libararies 下，检查 Code Sign on Copy。
    Under Embed Libraries, check Code Sign on Copy.
  3. 在 Link Binary With Libraries 下，设置状态为 Optional。（咱们使用动态链接，不需要静态链接）
    Under Link Binary With Libraries, set status to Optional. (We use dynamic linking, no need to statically link.)
3. 点击 Runner 然后进入 General 标签页。
  Click Runner and go to the General tab.
  1. 拖动 libyourlibrary.dylib 到 Frameworks, Libararies and Embedded Content 列表中。
    Drag libyourlibrary.dylib into the Frameworks, Libararies and Embedded Content list.
  2. 选择 Embed & Sign。
    Select Embed & Sign.
4. 点击 Runner 然后进入 Build Settings 标签页。
  Click Runner and go to the Build Settings tab.
  1. 在 Search Paths 部分，配置 Library Search Paths 确保 libyourlibrary.dylib 的路径包括在内。
    In the Search Paths section configure the Library Search Paths to include the path where libyourlibrary.dylib is located.
编辑 lib/main.dart 文件。
Edit lib/main.dart.
1. 使用 DynamicLibrary.open('libyourlibrary.dylib') 来动态链接符号表。
  Use DynamicLibrary.open('libyourlibrary.dylib') to dynamically link to the symbols.
2. 在 widget 的某个地方调用您的本地代码。
  Call your native function somewhere in a widget.
运行 flutter run 然后检查您的本地方法的调用结果。
Run flutter run and check that your native function gets called.
运行 flutter build macos 去构建一个自包含的 release 版本的应用。
Run flutter build macos to build a selfcontained release version of your app.

开源的三方库

Open-source third-party library

要创建一个包含 C/C++/Objective-C 和 Dart 代码的 Flutter 插件，请按照如下说明：

To create a Flutter plugin that includes both C/C++/Objective-C and Dart code, use the following instructions:

在您的插件项目打开 ios/<myproject>.podspec.
In your plugin project, open ios/<myproject>.podspec.
添加本地代码到 source_files 字段。
Add the native code to the source_files field.

本地代码会被静态链接到任何使用这个插件的应用二进制中。

The native code is then statically linked into the application binary of any app that uses this plugin.

闭源三方库

Closed-source third-party library

要创建包含 Dart 源代码，但 C/C++ 部分是以二进制形式分发的库的 Flutter 插件，请按照如下说明：

To create a Flutter plugin that includes Dart source code, but distribute the C/C++ library in binary form, use the following instructions:

在您的插件目录打开 ios/<myproject>.podspec。
In your plugin project, open ios/<myproject>.podspec.
添加 vendored_frameworks 字段。参考 CocoaPods 示例。
Add a vendored_frameworks field. See the CocoaPods example.

不要将此插件（或任何包含二进制代码的插件）上载到 pub.dev。相反，应该从可信的第三方下载此插件。如 CocoaPods 示例所示。

Do not upload this plugin (or any plugin containing binary code) to pub.dev. Instead, this plugin should be downloaded from a trusted third-party, as shown in the CocoaPods example.

Android

平台库

Platform library

如果要链接一个平台库，请按照如下说明：

To link against a platform library, use the following instructions:

在 Android 文档的 Android NDK Native APIs 列表中找到所需的库。它列出了稳定的本地 API。
Find the desired library in the Android NDK Native APIs list in the Android docs. This lists stable native APIs.
使用 DynamicLibrary.open 加载库。
Load the library using DynamicLibrary.open.

示例：加载 OpenGL ES (v3)：
For example, to load OpenGL ES (v3):
```
DynamicLibrary.open('libGLES_v3.so');
```

如果文档中有说明，您还需要根据说明更新 Android 应用程序或插件的清单文件。

You might need to update the Android manifest file of the app or plugin if indicated by the documentation.

第一方库

First-party library

对于应用程序或插件，以源代码或二进制形式包含本机代码的过程是相同的。

The process for including native code in source code or binary form is the same for an app or plugin.

开源三方库

Open-source third-party

遵循安卓文档中的添加 C 和 C++ 代码到项目来添加本地代码和对本地代码工具链的支持（CMake 或 ndk-build）。

Follow the Add C and C++ code to your project instructions in the Android docs to add native code and support for the native code toolchain (either CMake or ndk-build).

闭源三方库

Closed-source third-party library

要创建包含 Dart 源代码，但以二进制形式分发 C/C++ 库的 Flutter 插件，请按照如下说明：

To create a Flutter plugin that includes Dart source code, but distribute the C/C++ library in binary form, use the following instructions:

打开您项目的 android/build.gradle 文件。
Open the android/build.gradle file for your project.
添加 aar 工件添加为依赖。不要在您的 Flutter package 中导入工件。对应的，它需要在一个仓库中下载，比如 JCenter。
Add the AAR artifact as a dependency. Don’t include the artifact in your Flutter package. Instead, it should be downloaded from a repository, such as JCenter.

Web

目前不支持 Web 插件。

This feature is not yet supported for web plugins.

FAQ

Android APK 尺寸（共享对象压缩）

Android APK size (shared object compression)

Android 指南通常建议分发未压缩的本地共享对象，因为这种做法实际上可以节省设备空间。共享对象可以直接从 APK 加载，而不是将它们解压到设备上的临时位置然后再加载。 APK 是在传输过程中额外打包的 - 这就是为什么您应该查看下载的文件尺寸。

Android guidelines in general recommend distributing native shared objects uncompressed because that actually saves on device space. Shared objects can be directly loaded from the APK instead of unpacking them on device into a temporary location and then loading. APKs are additionally packed in transit - that is why you should be looking at download size.

Flutter APK 文件默认情况下不遵循这些指导原则来压缩 libflutter.so 和 libapp.so，这会导致 APK 体积更小，但在设备上体积更大。

Flutter APKs by default don’t follow these guidelines and compress libflutter.so and libapp.so - this leads to smaller APK size but larger on device size.

来自第三方的共享库可以使用其 AndroidManifest.xml 中的 android:extractNativeLibs="true" 更改此默认设置，来停止压缩 libflutter.so、libapp.so 和任何用户添加的共享库。要重新启用压缩，请按照如下方式重写您的 your_app_name/android/app/src/main/AndroidManifest.xml。

Shared objects from third parties can change this default setting with android:extractNativeLibs="true" in their AndroidManifest.xml and stop the compression of libflutter.so, libapp.so, and any user-added shared objects. To re-enable compression, override the setting in your_app_name/android/app/src/main/AndroidManifest.xml in the following way.

@@ -1,5 +1,6 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.example.your_app_name">
+    xmlns:tools="http://schemas.android.com/tools"
+    package="com.example.your_app_name" >
     <!-- io.flutter.app.FlutterApplication is an android.app.Application that
          calls FlutterMain.startInitialization(this); in its onCreate method.
          In most cases you can leave this as-is, but you if you want to provide
          additional functionality it is fine to subclass or reimplement
          FlutterApplication and put your custom class here. -->
@@ -8,7 +9,9 @@
     <application
         android:name="io.flutter.app.FlutterApplication"
         android:label="your_app_name"
-        android:icon="@mipmap/ic_launcher">
+        android:icon="@mipmap/ic_launcher"
+        android:extractNativeLibs="true"
+        tools:replace="android:extractNativeLibs">

删除的 iOS 符号

iOS symbols stripped

当创建一个 release 档案（IPA）时，符号会被 Xcode 删除。

When creating a release archive (IPA) the symbols are stripped by Xcode.

在 Xcode 中, 点击 Target Runner > Build Settings > Strip Style.
In Xcode, go to Target Runner > Build Settings > Strip Style.
将 All Symbols 修改为 Non-Global Symbols。
Change from All Symbols to Non-Global Symbols.

在 Flutter 应用中使用集成平台视图托管您的原生 Android 和 iOS 视图

Android
- 在 Dart 中进行的处理
  On the Dart side
  - 混合集成模式
    Hybrid composition
  - Virtual Display
- 在平台（Android）端
  On the platform side
iOS
- 在 Dart 端
  On the Dart side
- 在平台（iOS）端
  On the platform side
整合
Putting it together
性能
Performance

集成平台视图（后称为平台视图）允许将原生视图嵌入到 Flutter 应用中，所以您可以通过 Dart 将变换、裁剪和不透明度等效果应用到原生视图。

Platform views allow you to embed native views in a Flutter app, so you can apply transforms, clips, and opacity to the native view from Dart.

例如，这使您可以通过使用平台视图直接在 Flutter 应用内部使用 Android 和 iOS SDK 中的 Google Maps。

This allows you, for example, to use the native Google Maps from the Android and iOS SDKs directly inside your Flutter app, by using Platform Views.

本篇文档讨论了如何在您的 Flutter 应用中托管您的原生视图。

This page discusses how to host your own native views within a Flutter app.

Android

Flutter 支持两种集成模式：虚拟显示模式 (Virtual displays) 和混合集成模式 (Hybrid composition) 。

Flutter supports two modes: Virtual displays and Hybrid composition.

我们应根据具体情况来决定使用哪种模式。让我们来看看：

Which one to use depends on the use case. Let’s take a look:

虚拟显示模式会将 android.view.View 实例渲染为纹理，因此它不会嵌入到 Android Activity 的视图层次结构中。某些平台交互（例如键盘处理和辅助功能）可能无法正常工作。
Virtual displays renders the android.view.View instance to a texture, so it’s not embedded within the Android Activity’s view hierachy. Certain platform interactions such as keyboard handling, and accessibility features might not work.
混合集成模式需要 Flutter 1.22 （推荐使用 1.22.2 版本以及更高版本）。这种模式将原生的 android.view.View 附加到视图层次结构中。因此，键盘处理和无障碍功能是开箱即用的。在 Android 10 之前，此模式可能会大大降低 Flutter UI 的帧吞吐量 (FPS)。有关更多信息，请参见性能小节。
Hybrid composition requires Flutter 1.22 (version 1.22.2 or higher is recommended). This mode appends the native android.view.View to the view hierarchy. Therefore, keyboard handling, and accessibility work out of the box. Prior to Android 10, this mode might significantly reduce the frame throughput (FPS) of the Flutter UI. See performance for more info.

在 Android 上创建平台视图需要如下的步骤：

To create a platform view on Android, follow these steps:

在 Dart 中进行的处理

On the Dart side

在 Dart 端，创建一个 Widget 然后添加如下的实现，具体如下：

On the Dart side, create a Widget and add the following build implementation:

混合集成模式

Hybrid composition

在 Dart 文件中，例如 native_view_example.dart，请执行下列操作：

In your Dart file, for example native_view_example.dart, do the following:

添加下面的导入：

Add the following imports:

import 'package:flutter/foundation.dart';
import 'package:flutter/gestures.dart';
import 'package:flutter/rendering.dart';
import 'package:flutter/services.dart';

实现 build 方法：

Implement a build() method:

Widget build(BuildContext context) {
  // This is used in the platform side to register the view.
  final String viewType = '<platform-view-type>';
  // Pass parameters to the platform side.
  final Map<String, dynamic> creationParams = <String, dynamic>{};

  return PlatformViewLink(
    viewType: viewType,
    surfaceFactory:
        (BuildContext context, PlatformViewController controller) {
      return AndroidViewSurface(
        controller: controller as AndroidViewController,
        gestureRecognizers: const <Factory<OneSequenceGestureRecognizer>>{},
        hitTestBehavior: PlatformViewHitTestBehavior.opaque,
      );
    },
    onCreatePlatformView: (PlatformViewCreationParams params) {
      return PlatformViewsService.initSurfaceAndroidView(
        id: params.id,
        viewType: viewType,
        layoutDirection: TextDirection.ltr,
        creationParams: creationParams,
        creationParamsCodec: StandardMessageCodec(),
        onFocus: () {
          params.onFocusChanged(true);
        } ,
      )
        ..addOnPlatformViewCreatedListener(params.onPlatformViewCreated)
        ..create();
    },
  );
}

更多信息可以查看下面的 API 文档：

For more information, see the API docs for:

Virtual Display

在 Dart 文件中，例如 native_view_example.dart，请执行下列操作：

In your Dart file, for example native_view_example.dart, do the following:

添加下面的导入：
Add the following imports:
```
import 'package:flutter/widget.dart';
```

实现 build 方法：

Implement a build() method:

Widget build(BuildContext context) {
  // This is used in the platform side to register the view.
  final String viewType = 'hybrid-view-type';
  // Pass parameters to the platform side.
  final Map<String, dynamic> creationParams = <String, dynamic>{};

  return AndroidView(
    viewType: viewType,
    layoutDirection: TextDirection.ltr,
    creationParams: creationParams,
    creationParamsCodec: const StandardMessageCodec(),
  );
}

更多信息，查阅 API 文档：

For more information, see the API docs for:

AndroidView

在平台（Android）端

On the platform side

在平台端，使用 Java 或 Kotlin 中的标准包 io.flutter.plugin.platform：

On the platform side, use the standard io.flutter.plugin.platform package in either Java or Kotlin:

Kotlin
Java

在您的原生代码中，实现如下方法：

In your native code, implement the following:

继承 io.flutter.plugin.platform.PlatformView 以提供对 android.view.View 的引用，如 NativeView.kt 所示：

Extend io.flutter.plugin.platform.PlatformView to provide a reference to the android.view.View, For example NativeView.kt:

package dev.flutter.example

import android.content.Context
import android.graphics.Color
import android.view.View
import android.widget.TextView
import io.flutter.plugin.platform.PlatformView

internal class NativeView(context: Context, id: Int, creationParams: Map<String?, Any?>?) : PlatformView {
    private val textView: TextView

    override fun getView(): View {
        return textView
    }

    override fun dispose() {}

    init {
        textView = TextView(context)
        textView.textSize = 72f
        textView.setBackgroundColor(Color.rgb(255, 255, 255))
        textView.text = "Rendered on a native Android view (id: $id)"
    }
}

创建一个用来创建 NativeView 的实例的工厂类，参考 NativeViewFactory.kt：

Create a factory class that creates an instance of the NativeView created earlier, for example NativeViewFactory.kt:

package dev.flutter.example

import android.content.Context
import android.view.View
import io.flutter.plugin.common.StandardMessageCodec
import io.flutter.plugin.platform.PlatformView
import io.flutter.plugin.platform.PlatformViewFactory

class NativeViewFactory : PlatformViewFactory(StandardMessageCodec.INSTANCE) {
    override fun create(context: Context, viewId: Int, args: Any?): PlatformView {
        val creationParams = args as Map<String?, Any?>?
        return NativeView(context, viewId, creationParams)
    }
}

最后，注册这个平台视图。这一步可以在应用中，也可以在插件中。

Finally, register the platform view. This can be done in an app or a plugin.

要在应用中进行注册，修改应用的主 Activity （例如：MainActivity.kt）：

For app registration, modify the app’s main activity (for example, MainActivity.kt):

package dev.flutter.example

import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine

class MainActivity : FlutterActivity() {
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        flutterEngine
                .platformViewsController
                .registry
                .registerViewFactory("<platform-view-type>", NativeViewFactory())
    }
}

要在插件中进行注册，修改您插件的主类（例如：PlatformViewPlugin.kt）：

For plugin registration, modify the plugin’s main class (for example, PlatformViewPlugin.kt):

package dev.flutter.plugin.example

import io.flutter.embedding.engine.plugins.FlutterPlugin
import io.flutter.embedding.engine.plugins.FlutterPlugin.FlutterPluginBinding

class PlatformViewPlugin : FlutterPlugin {
    override fun onAttachedToEngine(binding: FlutterPluginBinding) {
        binding
                .platformViewRegistry
                .registerViewFactory("<platform-view-type>", NativeViewFactory())
    }

    override fun onDetachedFromEngine(binding: FlutterPluginBinding) {}
}

在您的原生代码中，实现如下方法：

In your native code, implement the following:

继承 io.flutter.plugin.platform.PlatformView 以提供对 android.view.View 的引用，如 NativeView.java 所示：

Extend io.flutter.plugin.platform.PlatformView to provide a reference to the android.view.View, For example, NativeView.java:

package dev.flutter.example;

import android.content.Context;
import android.graphics.Color;
import android.view.View;
import android.widget.TextView;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import io.flutter.plugin.platform.PlatformView;
import java.util.Map;

class NativeView implements PlatformView {
   @NonNull private final TextView textView;

    NativeView(@NonNull Context context, int id, @Nullable Map<String, Object> creationParams) {
        textView = new TextView(context);
        textView.setTextSize(72);
        textView.setBackgroundColor(Color.rgb(255, 255, 255));
        textView.setText("Rendered on a native Android view (id: " + id + ")");
    }

    @NonNull
    @Override
    public View getView() {
        return textView;
    }

    @Override
    public void dispose() {}
}

创建一个用来创建 NativeView 的实例的工厂类，参考 NativeViewFactory.java：

Create a factory class that creates an instance of the NativeView created earlier, for example, NativeViewFactory.java:

package dev.flutter.example;

import android.content.Context;
import android.view.View;
import androidx.annotation.Nullable;
import androidx.annotation.NonNull;
import io.flutter.plugin.common.BinaryMessenger;
import io.flutter.plugin.common.StandardMessageCodec;
import io.flutter.plugin.platform.PlatformView;
import io.flutter.plugin.platform.PlatformViewFactory;
import java.util.Map;

class NativeViewFactory extends PlatformViewFactory {
  @NonNull private final BinaryMessenger messenger;
  @NonNull private final View containerView;

  NativeViewFactory(@NonNull BinaryMessenger messenger, @NonNull View containerView) {
    super(StandardMessageCodec.INSTANCE);
    this.messenger = messenger;
    this.containerView = containerView;
  }

  @NonNull
  @Override
  public PlatformView create(@NonNull Context context, int id, @Nullable Object args) {
    final Map<String, Object> creationParams = (Map<String, Object>) args;
    return new NativeView(context, id, creationParams);
  }
}

最后，注册这个平台视图。这一步可以在应用中，也可以在插件中。

Finally, register the platform view. This can be done in an app or a plugin.

要在应用中进行注册，修改应用的主 Activity （例如：MainActivity.java）：

For app registration, modify the app’s main activity (for example, MainActivity.java):

package dev.flutter.example;

import androidx.annotation.NonNull;
import io.flutter.embedding.android.FlutterActivity;
import io.flutter.embedding.engine.FlutterEngine;

public class MainActivity extends FlutterActivity {
    @Override
    public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
        flutterEngine
            .getPlatformViewsController()
            .getRegistry()
            .registerViewFactory("<platform-view-type>", new NativeViewFactory());
    }
}

要在插件中进行注册，修改插件的主类（例如：PlatformViewPlugin.java）：

For plugin registration, modify the plugin’s main file (for example, PlatformViewPlugin.java):

package dev.flutter.plugin.example;

import androidx.annotation.NonNull;
import io.flutter.embedding.engine.plugins.FlutterPlugin;
import io.flutter.plugin.common.BinaryMessenger;

public class PlatformViewPlugin implements FlutterPlugin {
  @Override
  public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
    binding
        .getPlatformViewRegistry()
        .registerViewFactory("<platform-view-type>", new NativeViewFactory());
  }

  @Override
  public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {}
}

更多信息，请查看 API 文档：

For more information, see the API docs for:

最后，修改您的 build.gradle 文件来满足 Android SDK 最低版本的要求：

Finally, modify your build.gradle file to require one of the minimal Android SDK versions:

android {
    defaultConfig {
        minSdkVersion 19 // if using Hybrid composition.
        minSdkVersion 20 // if using Virtual display.
    }
}

iOS

iOS 只支持混合集成模式，这意味着原生的 UIView 会被加入视图层级中。

iOS only uses Hybrid composition, which means that the native UIView is appended to view hierarchy.

在 Flutter 1.22 前，平台视图是一个开发者预览的版本。在 1.22 或更高版本中则不再是这样了，所以我们不再需要在 Info.plist 中设置 io.flutter.embedded_views_preview 标识。

Prior to Flutter 1.22, platform views were in developers preview. In 1.22 or above, this is no longer the case, so there’s no need to set the io.flutter.embedded_views_preview flag in Info.plist.

要在 iOS 中创建平台视图，需要如下步骤：

To create a platform view on iOS, follow these steps:

在 Dart 端

On the Dart side

在 Dart 端，创建一个 Widget 并添加如下的实现，具体如下：

On the Dart side, create a Widget and add the following build implementation, as shown in the following steps.

在 Dart 文件中，例如 native_view_example.dart，请执行下列操作：

In your Dart file, for example do the following in native_view_example.dart:

添加如下导入：
Add the following imports:
```
import 'package:flutter/widgets.dart';
```

实现 build 方法：

Implement a build() method:

Widget build(BuildContext context) {
  // This is used in the platform side to register the view.
  final String viewType = '<platform-view-type>';
  // Pass parameters to the platform side.
  final Map<String, dynamic> creationParams = <String, dynamic>{};

  return UiKitView(
    viewType: viewType,
    layoutDirection: TextDirection.ltr,
    creationParams: creationParams,
    creationParamsCodec: const StandardMessageCodec(),
  );
}

更多信息，请查看 API 文档： UIKitView.

For more information, see the API docs for: UIKitView.

在平台（iOS）端

On the platform side

在平台端，您可以使用 Swift 或是 Objective-C：

On the platform side, you use the either Swift or Objective-C:

Swift
Objective-C

实现工厂和平台视图。 FLNativeViewFactory 创建一个关联了 UIView 的平台视图。举个例子，FLNativeView.swift：

Implement the factory and the platform view. The FLNativeViewFactory creates the platform view, and the platform view provides a reference to the UIView. For example, FLNativeView.swift:

import Flutter
import UIKit

class FLNativeViewFactory: NSObject, FlutterPlatformViewFactory {
    private var messenger: FlutterBinaryMessenger

    init(messenger: FlutterBinaryMessenger) {
        self.messenger = messenger
        super.init()
    }

    func create(
        withFrame frame: CGRect,
        viewIdentifier viewId: Int64,
        arguments args: Any?
    ) -> FlutterPlatformView {
        return FLNativeView(
            frame: frame,
            viewIdentifier: viewId,
            arguments: args,
            binaryMessenger: messenger)
    }
}

class FLNativeView: NSObject, FlutterPlatformView {
    private var _view: UIView

    init(
        frame: CGRect,
        viewIdentifier viewId: Int64,
        arguments args: Any?,
        binaryMessenger messenger: FlutterBinaryMessenger?
    ) {
        _view = UIView()
        super.init()
        // iOS views can be created here
        createNativeView(view: _view)
    }

    func view() -> UIView {
        return _view
    }

    func createNativeView(view _view: UIView){
        _view.backgroundColor = UIColor.blue
        let nativeLabel = UILabel()
        nativeLabel.text = "Native text from iOS"
        nativeLabel.textColor = UIColor.white
        nativeLabel.textAlignment = .center
        nativeLabel.frame = CGRect(x: 0, y: 0, width: 180, height: 48.0)
        _view.addSubview(nativeLabel)
    }
}

最后，注册这个平台视图。这一步可以在应用中，也可以在插件中。

Finally, register the platform view. This can be done in an app or a plugin.

要在应用中进行注册，修改应用中的 AppDelegate.swift：

For app registration, modify the App’s AppDelegate.swift:

import Flutter
import UIKit

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]?
    ) -> Bool {
        GeneratedPluginRegistrant.register(with: self)

        weak var registrar = self.registrar(forPlugin: "plugin-name")

        let factory = FLNativeViewFactory(messenger: registrar!.messenger())
        self.registrar(forPlugin: "<plugin-name>")!.register(
            factory,
            withId: "<platform-view-type>")
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

要在插件中进行注册，修改插件的主类（例如 FLPlugin.swift）：

For plugin registration, modify the plugin’s main file (for example, FLPlugin.swift):

import Flutter
import UIKit

class FLPlugin: NSObject, FlutterPlugin {
    public static func register(with registrar: FlutterPluginRegistrar) {
        let factory = FLNativeViewFactory(messenger: registrar.messenger)
        registrar.register(factory, withId: "<platform-view-type>")
    }
}

在工厂类和平台视图的文件头部添加以下内容。用 FLNativeView.h 举例：

Add the headers for the factory and the platform view. For example, FLNativeView.h:

#import <Flutter/Flutter.h>

@interface FLNativeViewFactory : NSObject <FlutterPlatformViewFactory>
- (instancetype)initWithMessenger:(NSObject<FlutterBinaryMessenger>*)messenger;
@end

@interface FLNativeView : NSObject <FlutterPlatformView>

- (instancetype)initWithFrame:(CGRect)frame
               viewIdentifier:(int64_t)viewId
                    arguments:(id _Nullable)args
              binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger;

- (UIView*)view;
@end

实现工厂类和平台视图。 FLNativeViewFactory 创建一个关联了 UIView 的平台视图。用 FLNativeView.m 举例：

Implement the factory and the platform view. The FLNativeViewFactory creates the platform view, and the platform view provides a reference to the UIView. For example, FLNativeView.m:

#import "FLNativeView.h"

@implementation FLNativeViewFactory {
  NSObject<FlutterBinaryMessenger>* _messenger;
}

- (instancetype)initWithMessenger:(NSObject<FlutterBinaryMessenger>*)messenger {
  self = [super init];
  if (self) {
    _messenger = messenger;
  }
  return self;
}

- (NSObject<FlutterPlatformView>*)createWithFrame:(CGRect)frame
                                   viewIdentifier:(int64_t)viewId
                                        arguments:(id _Nullable)args {
  return [[FLNativeView alloc] initWithFrame:frame
                              viewIdentifier:viewId
                                   arguments:args
                             binaryMessenger:_messenger];
}

@end

@implementation FLNativeView {
   UIView *_view;
}

- (instancetype)initWithFrame:(CGRect)frame
               viewIdentifier:(int64_t)viewId
                    arguments:(id _Nullable)args
              binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger {
  if (self = [super init]) {
    _view = [[UIView alloc] init];
  }
  return self;
}

- (UIView*)view {
  return _view;
}

@end

最后，注册这个平台视图。这一步可以在应用中，也可以在插件中。

Finally, register the platform view. This can be done in an app or a plugin.

要在应用中进行注册，修改应用中的 AppDelegate.m：

For app registration, modify the App’s AppDelegate.m:

#import "AppDelegate.h"
#import "FLNativeView.h"
#import "GeneratedPluginRegistrant.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [GeneratedPluginRegistrant registerWithRegistry:self];

   NSObject<FlutterPluginRegistrar>* registrar =
      [self registrarForPlugin:@"plugin-name"];

  FLNativeViewFactory* factory =
      [[FLNativeViewFactory alloc] initWithMessenger:registrar.messenger];

  [[self registrarForPlugin:@"<plugin-name>"] registerViewFactory:factory
                                                          withId:@"<platform-view-type>"];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end

要在插件中进行注册，修改插件主文件（例如 FLPlugin.m）：

For plugin registration, modify the main plugin file (for example, FLPlugin.m):

#import <Flutter/Flutter.h>
#import "FLNativeView.h"

@interface FLPlugin : NSObject<FlutterPlugin>
@end

@implementation FLPlugin

+ (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar {
  FLNativeViewFactory* factory =
      [[FLNativeViewFactory alloc] initWithMessenger:registrar.messenger];
  [registrar registerViewFactory:factory withId:@"<platform-view-type>"];
}

@end

更多信息，请查看 API 文档：

For more information, see the API docs for:

整合

Putting it together

在 Dart 中实现 build() 方法时，您可以使用 defaultTargetPlatform 来检测当前的平台，并且决定如何使用这个 widget：

When implementing the build() method in Dart, you can use defaultTargetPlatform to detect the platform, and decide what widget to use:

Widget build(BuildContext context) {
  // This is used in the platform side to register the view.
  final String viewType = '<platform-view-type>';
  // Pass parameters to the platform side.
  final Map<String, dynamic> creationParams = <String, dynamic>{};

  switch (defaultTargetPlatform) {
    case TargetPlatform.android:
      // return widget on Android.
    case TargetPlatform.iOS:
      // return widget on iOS.
    default:
      throw UnsupportedError("Unsupported platform view");
  }
}

性能

Performance

在 Flutter 中使用平台视图时，性能会有所折衷。

Platform views in Flutter come with performance trade-offs.

例如，在典型的 Flutter 应用中，Flutter UI 是在专用栅格线程上组成的。由于平台的主线程很少被阻塞，因此 Flutter 应用程序可以快速运行。

For example, in a typical Flutter app, the Flutter UI is composed on a dedicated raster thread. This allows Flutter apps to be fast, as the main platform thread is rarely blocked.

使用混合集成模式渲染平台视图时， Flutter UI 由平台线程完成，与其他线程一起竞争，例如：处理系统或插件消息等任务。

While a platform view is rendered with Hybrid composition, the Flutter UI is composed from the platform thread, which competes with other tasks like handling OS or plugin messages.

在 Android 10 之前，混合集成模式将每个 Flutter 帧从显存中复制到主内存中，然后再将其复制回 GPU 纹理中。在 Android 10 或更高版本中，显存会被复制两次。由于每帧都会进行一次复制，因此可能会影响整个 Flutter UI 的性能。

Prior to Android 10, Hybrid composition copies each Flutter frame out of the graphic memory into main memory, and then copies it back to a GPU texture. In Android 10 or above, the graphics memory is copied twice. As this copy happens per frame, the performance of the entire Flutter UI may be impacted.

另一方面，虚拟显示模式使平台视图的每个像素流经附加的中间图形缓冲区，这会浪费显存和绘图性能。

Virtual display, on the other hand, makes each pixel of the native view flow through additional intermediate graphic buffers, which cost graphic memory and drawing performance.

对于复杂的情况，可以使用一些技巧来缓解这些问题。

For complex cases, there are some techniques that can be used to mitigate these issues.

例如，当 Dart 中发生动画时，您可以使用占位符纹理。换句话说，如果在渲染平台视图时动画很慢，请考虑对原生视图进行截图，并将其渲染为纹理。

For example, you could use a placeholder texture while an animation is happening in Dart. In other words, if an animation is slow while a platform view is rendered, then consider taking a screenshot of the native view and rendering it as a texture.

更多消息，查看：

For more information, see:

Web 常见问题

Web 版本的 Flutter 是否已经准备好投入生产环境中了呢？
Is the web version of Flutter ready for production?
在 Web 平台使用 Flutter 的场景有哪些？
What scenarios are ideal for Flutter on the web?
我应该如何提交 web 支持相关的 issue
How do I file an issue about web support?
如何创建同时在 Web 上运行的应用？
How do I create an app that also runs on the web?
我该如何在浏览器中刷新正在运行的应用？
Does hot reload work with a web app?
我该如何在浏览器中重启正在运行的应用？
How do I restart the app running in the browser?
现在有哪些浏览器支持 Flutter 了？
Which web browsers are supported by Flutter?
我可以在任意 IDE 中，构建、运行并发布 web 应用吗？
Can I build, run, and deploy web apps in any of the IDEs?
我该如何构建响应式 web 应用？
How do I build a responsive app for the web?
我能使用 Flutter 插件么？
Can I use Flutter plugins?
我能在 Web 应用中使用 dart:io 这个 package 吗？
Can I use dart:io with a web app?
我应该如何处理一个 Web 平台特定的导入？
How do I handle web-specific imports?
我该如何把一个 Flutter web 应用嵌入到一个网页中？
How do I embed a Flutter web app in a web page?
我该如何调试一个 web 应用？
How do I debug a web app?
我该如何测试 Web 应用？
How do I test a web app?
How do I internationalize a web app?
我该如何部署 Web 应用？
How do I deploy a web app?
Platform.is API 现在可用吗？
Does Platform.is work on the web?
如何跟其他使用者交流？
How can I compare notes with others who are playing with this feature?

Web 版本的 Flutter 是否已经准备好投入生产环境中了呢？

Is the web version of Flutter ready for production?

Flutter 网页端的支持正式在稳定版渠道发布，提供了以应用为中心的框架，框架以现代 Web 平台的功能为基础，如果希望了解更多，请查看文章 Flutter Web 支持现已进入稳定版。

Flutter’s web support is now available on the stable channel, offering an app-centric framework that builds on the power of the modern web platform. Find out more details about Flutter’s production quality support for the web.

在 Web 平台使用 Flutter 的场景有哪些？

What scenarios are ideal for Flutter on the web?

Flutter 目前并非适用于所有的网页内容，不过我们主要关注三个应用场景：

Not every web page makes sense in Flutter, but we think Flutter is particularly suited for app-centric experiences:

渐进式 web 应用 (Progressive web apps, PWA)，兼具 web 的高覆盖面与桌面应用的强大功能。
Progressive Web Apps
单页应用 (Single page apps, SPA)，只需一次加载，并与互联网服务动态互传数据。
Single Page Apps
将现有 Flutter 移动应用拓展到 web，在两个平台共享代码。
Existing Flutter mobile apps

现在阶段，Flutter 不适合具有丰富文本和瀑布流的页面。例如，博客文章等基于流媒体的丰富文本内容，其受益于网络构建的以文档为中心的模式，而不是像 Flutter 这样的 UI 框架可以提供的以应用为中心的服务。然而，你可以使用 Flutter 将交互式体验嵌入到这些网站中。

At this time, Flutter is not suitable for static websites with text-rich flow-based content. For example, blog articles benefit from the document-centric model that the web is built around, rather than the app-centric services that a UI framework like Flutter can deliver. However, you can use Flutter to embed interactive experiences into these websites.

有关如何在 Web 上使用 Flutter 的更多信息，参考文档： Flutter 的 Web 支持。

For more information on how you can use Flutter on the web, see Web support for Flutter.

我应该如何提交 web 支持相关的 issue

How do I file an issue about web support?

你可以在 Flutter 主仓库中发起一个 issue。请确保标题中包含了 “web” 关键字。

You can file an issue on the main Flutter repo. Make sure that “web” is included in the title.

如何创建同时在 Web 上运行的应用？

How do I create an app that also runs on the web?

请参见使用 Flutter 构建 Web 应用。

See building a web app with Flutter.

我该如何在浏览器中刷新正在运行的应用？

Does hot reload work with a web app?

不能，但是可以使用热重启 (hot restart)。热重启是可以您的应用快速响应改动的方法，无需等待重新编译的载入。它与移动端的热重载功能类似。唯一的区别是热重载可以保持应用的状态。

No, but you can use hot restart. Hot restart is a fast way of seeing your changes without having to relaunch your web app and wait for it to compile and load. This works similarly to the hot reload feature for Flutter mobile development. The only difference is that hot reload remembers your state and hot restart doesn’t.

我该如何在浏览器中重启正在运行的应用？

How do I restart the app running in the browser?

使用浏览器的刷新按钮不会起作用，但你可以在执行 flutter run -d chrome 的控制台中输入「R」进行刷新。

Using the browser’s refresh button doesn’t work, but you can enter “R” in the console where “flutter run -d chrome” is running.

现在有哪些浏览器支持 Flutter 了？

Which web browsers are supported by Flutter?

现在 Flutter web 应用可以运行在以下浏览器中：

Flutter web apps can run on the following browsers:

Chrome（移动和桌面端）
Chrome (mobile & desktop)
Safari（移动和桌面端）
Safari (mobile & desktop)
Edge（移动和桌面端）
Edge (mobile & desktop)
Firefox（移动和桌面端）
Firefox (mobile & desktop)

在开发阶段，Chrome（在 macOS、Windows 以及 Linux）以及 Edge（在 Windows 上）将作为默认浏览器用于调试。

During development, Chrome (on macOS, Windows, and Linux) and Edge (on Windows) are supported as the default browsers for debugging your app.

我可以在任意 IDE 中，构建、运行并发布 web 应用吗？

Can I build, run, and deploy web apps in any of the IDEs?

你可以在 Android Studio/IntelliJ 和 VS Code 里选择使用 Chrome 或者 Edge 浏览器。

You can select Chrome or Edge as the target device in Android Studio/IntelliJ and VS Code.

设备下拉列表里现在应该在所有平台里都包含了 Chrome (web)。

The device pulldown should now include the Chrome (web) option for all channels.

我该如何构建响应式 web 应用？

How do I build a responsive app for the web?

请参阅创建响应式应用。

See Creating responsive apps.

我能使用 Flutter 插件么？

Can I use Flutter plugins?

是的，目前有很多插件已经支持了 web。在 pub.dev 上使用 web 过滤以找到更新的插件清单。你也可以为已有的或者你自己编写的 plugin 添加 web 支持。

Yes, several plugins have web support. Find an updated list of plugins on pub.dev using the web filter. You can also add web support to existing plugins or write your own plugins for the web.

我能在 Web 应用中使用 `dart:io` 这个 package 吗？

Can I use `dart:io` with a web app?

不行。文件系统在浏览器中是无法访问的。对于网络功能来说，请使用 http package。请注意，安全方面的工作有所不同，因为浏览器（而不是应用程序）控制 HTTP 请求上的标头。

No. The file system is not accessible from the browser. For network functionality, use the http package. Note that security works somewhat differently because the browser (and not the app) controls the headers on an HTTP request.

我应该如何处理一个 Web 平台特定的导入？

How do I handle web-specific imports?

部分插件需要在特定平台导入库或者文件，尤其是当使用浏览器无法访问的文件系统时。若要在你的应用里使用这些插件，请参阅 dart.cn：选择性的导入。

Some plugins require platform-specific imports, particularly if they use the file system, which is not accessible from the browser. To use these plugins in your app, see the documentation for conditional imports on dart.dev.

我该如何把一个 Flutter web 应用嵌入到一个网页中？

How do I embed a Flutter web app in a web page?

你可以通过下面这个例子，以 iframe 来内嵌，把 URL 替换成托管 Flutter Web 的页面 URL：

You can embed a Flutter web app, as you would embed other content, in an iframe tag of an HTML file. In the following example, replace “URL” with the location of your hosted HTML page:

<iframe src="URL"></iframe>

如果你遇到问题，请提交一个 issue 给我们。

If you encounter problems, please file an issue.

我该如何调试一个 web 应用？

How do I debug a web app?

使用 Flutter DevTools 来尝试如下工作：

Use Flutter DevTools for the following tasks:

使用 Chrome DevTools 来尝试如下工作：

Use Chrome DevTools for the following tasks:

生成事件的时间线
Generating event timeline
分析性能——请确保应用使用的是 profile 构建
Analyzing performance—make sure to use a profile build

我该如何测试 Web 应用？

How do I test a web app?

使用常规的 widget tests，了解更多关于如何在浏览器里使用集成测试，请查看集成测试文档页面。

Use widget tests or integration tests. To learn more about running integration tests in a browser, see the Integration testing page.

How do I internationalize a web app?

与 Flutter 移动应用的国际化无差别。

This isn’t any different than internationalizing a Flutter mobile app.

我该如何部署 Web 应用？

How do I deploy a web app?

请参阅打包并发布到 Web 平台。

See Preparing a web app for release.

`Platform.is` API 现在可用吗？

Does `Platform.is` work on the web?

目前还不行。

Not currently.

如何跟其他使用者交流？

How can I compare notes with others who are playing with this feature?

请在 Discord 平台的 #web 这个讨论板跟大家讨论， Flutter 团队的工程师会经常阅读和互动。

Check out the #web discussion channel on Discord. Flutter engineers routinely read and respond on Discord.

撰写双端平台代码（插件编写实现）

架构概述：平台通道
Architectural overview: platform channels
- 平台通道数据类型及编解码器
  Platform channel data types support and codecs
示例: 通过平台通道调用平台的 iOS 和 Android 代码
Example: Calling platform-specific iOS and Android code using platform channels
通过 Pigeon 获得类型安全的通道
Typesafe platform channels via Pigeon
- Pigeon 样例
  Pigeon example
从 UI 代码中分离平台相关代码
Separate platform-specific code from UI code
将平台相关代码作为 Package 进行提交
Publish platform-specific code as a package
自定义通道和编解码器
Custom channels and codecs
通道和平台线程
Channels and Platform Threading

本指南介绍了如何编写自定义的平台相关代码，某些平台相关功能可通过已有的软件包获得，具体细节可查看：在 Flutter 里使用 Packages。

This guide describes how to write custom platform-specific code. Some platform-specific functionality is available through existing packages; see using packages.

Flutter 使用了灵活的系统，它允许你调用相关平台的 API，无论是 Android 中的 Java 或 Kotlin 代码，还是 iOS 中的 Objective-C 或 Swift 代码。

Flutter uses a flexible system that allows you to call platform-specific APIs whether available in Kotlin or Java code on Android, or in Swift or Objective-C code on iOS.

Flutter uses a flexible system that allows you to call platform-specific APIs in a language that works directly with those APIs:

Kotlin or Java on Android
Swift or Objective-C on iOS
C++ on Windows
Objective-C on macOS
C on Linux

Flutter 使用了灵活系统，无论是在 Android 上的 Kotlin 还是 Java，亦或是 iOS 上的 Swift 或 Objective-C，它都允许你调用平台特定 API。

Flutter 内置的平台特定 API 支持不依赖于任何生成代码，而是灵活的依赖于传递消息格式。或者，你也可以使用 Pigeon 这个 package，通过生成代码来发送结构化类型安全消息。

Flutter’s builtin platform-specific API support does not rely on code generation, but rather on a flexible message passing style. Alternatively, the package Pigeon can be used for sending structured typesafe messages via code generation:

应用中的 Flutter 部分通过平台通道向其宿主 (非 Dart 部分) 发送消息。
The Flutter portion of the app sends messages to its host, the non-Dart portion of the app, over a platform channel.
宿主监听平台通道并接收消息。然后，它使用原生编程语言来调用任意数量的相关平台 API，并将响应发送回客户端（即应用程序中的 Flutter 部分）。
The host listens on the platform channel, and receives the message. It then calls into any number of platform-specific APIs—using the native programming language—and sends a response back to the client, the Flutter portion of the app.

架构概述：平台通道

Architectural overview: platform channels

消息使用平台通道在客户端（UI）和宿主（平台）之间传递，如下图所示：

Messages are passed between the client (UI) and host (platform) using platform channels as illustrated in this diagram:

Platform channels architecture

消息和响应以异步的形式进行传递，以确保用户界面能够保持响应。

Messages and responses are passed asynchronously, to ensure the user interface remains responsive.

客户端做方法调用的时候 MethodChannel 会负责响应，从平台一侧来讲，Android 系统上使用 MethodChannelAndroid、 iOS 系统使用 MethodChanneliOS 来接收和返回来自 MethodChannel 的方法调用。在开发平台插件的时候，可以减少样板代码。

On the client side, MethodChannel enables sending messages that correspond to method calls. On the platform side, MethodChannel on Android (MethodChannelAndroid) and FlutterMethodChannel on iOS (MethodChanneliOS) enable receiving method calls and sending back a result. These classes allow you to develop a platform plugin with very little ‘boilerplate’ code.

平台通道数据类型及编解码器

Platform channel data types support and codecs

标准平台通道使用标准消息编解码器，它支持简单的类似 JSON 值的高效二进制序列化，例如布尔值、数字、字符串、字节缓冲区及这些类型的列表和映射（详情请参阅 StandardMessageCodec）。当你发送和接收值时，它会自动对这些值进行序列化和反序列化。

The standard platform channels use a standard message codec that supports efficient binary serialization of simple JSON-like values, such as booleans, numbers, Strings, byte buffers, and Lists and Maps of these (see StandardMessageCodec for details). The serialization and deserialization of these values to and from messages happens automatically when you send and receive values.

下表展示了如何在平台端接收 Dart 值，反之亦然：

The following table shows how Dart values are received on the platform side and vice versa:

Dart	Java
null	null
bool	java.lang.Boolean
int	java.lang.Integer
int, if 32 bits not enough	java.lang.Long
double	java.lang.Double
String	java.lang.String
Uint8List	byte[]
Int32List	int[]
Int64List	long[]
Float32List	float[]
Float64List	double[]
List	java.util.ArrayList
Map	java.util.HashMap

Dart	Kotlin
null	null
bool	Boolean
int	Int
int, if 32 bits not enough	Long
double	Double
String	String
Uint8List	ByteArray
Int32List	IntArray
Int64List	LongArray
Float32List	FloatArray
Float64List	DoubleArray
List	List
Map	HashMap

Dart	Objective-C
null	nil (NSNull when nested)
bool	NSNumber numberWithBool:
int	NSNumber numberWithInt:
int, if 32 bits not enough	NSNumber numberWithLong:
double	NSNumber numberWithDouble:
String	NSString
Uint8List	FlutterStandardTypedData typedDataWithBytes:
Int32List	FlutterStandardTypedData typedDataWithInt32:
Int64List	FlutterStandardTypedData typedDataWithInt64:
Float32List	FlutterStandardTypedData typedDataWithFloat32:
Float64List	FlutterStandardTypedData typedDataWithFloat64:
List	NSArray
Map	NSDictionary

Dart	Swift
null	nil
bool	NSNumber(value: Bool)
int	NSNumber(value: Int32)
int, if 32 bits not enough	NSNumber(value: Int)
double	NSNumber(value: Double)
String	String
Uint8List	FlutterStandardTypedData(bytes: Data)
Int32List	FlutterStandardTypedData(int32: Data)
Int64List	FlutterStandardTypedData(int64: Data)
Float32List	FlutterStandardTypedData(float32: Data)
Float64List	FlutterStandardTypedData(float64: Data)
List	Array
Map	Dictionary

Dart	C++
null	EncodableValue()
bool	EncodableValue(bool)
int	EncodableValue(int32_t)
int, if 32 bits not enough	EncodableValue(int64_t)
double	EncodableValue(double)
String	EncodableValue(std::string)
Uint8List	EncodableValue(std::vector)
Int32List	EncodableValue(std::vector)
Int64List	EncodableValue(std::vector)
Float32List	EncodableValue(std::vector)
Float64List	EncodableValue(std::vector)
List	EncodableValue(std::vector)
Map	EncodableValue(std::map<EncodableValue, EncodableValue>)

Dart	C (GObject)
null	FlValue()
bool	FlValue(bool)
int	FlValue(int62_t)
double	FlValue(double)
String	FlValue(gchar*)
Uint8List	FlValue(uint8_t*)
Int32List	FlValue(int32_t*)
Int64List	FlValue(int64_t*)
Float32List	FlValue(float*)
Float64List	FlValue(double*)
List	FlValue(FlValue)
Map	FlValue(FlValue, FlValue)

示例: 通过平台通道调用平台的 iOS 和 Android 代码

Example: Calling platform-specific iOS and Android code using platform channels

以下代码演示了如何调用平台相关 API 来检索并显示当前的电池电量。它通过平台消息 getBatteryLevel() 来调用 Android 的 BatteryManager API 及 iOS 的 device.batteryLevel API。

The following code demonstrates how to call a platform-specific API to retrieve and display the current battery level. It uses the Android BatteryManager API, and the iOS device.batteryLevel API, via a single platform message, getBatteryLevel().

该示例在主应用程序中添加平台相关代码。如果想要将该代码重用于多个应用程序，那么项目的创建步骤将略有差异（查看 Flutter Packages 的开发和提交），但平台通道代码仍以相同方式编写。

The example adds the platform-specific code inside the main app itself. If you want to reuse the platform-specific code for multiple apps, the project creation step is slightly different (see developing packages), but the platform channel code is still written in the same way.

注意：可在 /examples/platform_channel/ 中获得使用 Java 实现的 Android 及使用 Objective-C 实现的 iOS 的该示例完整可运行的代码。对于用 Swift 实现的 iOS 代码，请参阅 /examples/platform_channel_swift/。

Note: The full, runnable source-code for this example is available in /examples/platform_channel/ for Android with Java and iOS with Objective-C. For iOS with Swift, see /examples/platform_channel_swift/.

第一步：创建一个新的应用项目

Step 1: Create a new app project

首先创建一个新的应用：

Start by creating a new app:

在终端中运行：flutter create batterylevel
In a terminal run: flutter create batterylevel

默认情况下，我们的模板使用 Kotlin 编写 Android 或使用 Swift 编写 iOS 代码。要使用 Java 或 Objective-C，请使用 -i 和/或 -a 标志：

By default our template supports writing Android code using Kotlin, or iOS code using Swift. To use Java or Objective-C, use the -i and/or -a flags:

在终端中运行：flutter create -i objc -a java batterylevel
In a terminal run: flutter create -i objc -a java batterylevel

第二步：创建 Flutter 平台客户端

Step 2: Create the Flutter platform client

应用程序的 State 类保持当前应用的状态。扩展它以保持当前的电池状态。

The app’s State class holds the current app state. Extend that to hold the current battery state.

首先，构建通道。在返回电池电量的单一平台方法中使用 MethodChannel。

First, construct the channel. Use a MethodChannel with a single platform method that returns the battery level.

通道的客户端和宿主端通过传递给通道构造函数的通道名称进行连接。一个应用中所使用的所有通道名称必须是唯一的；使用唯一的 域前缀 为通道名称添加前缀，比如：samples.flutter.dev/battery。

The client and host sides of a channel are connected through a channel name passed in the channel constructor. All channel names used in a single app must be unique; prefix the channel name with a unique ‘domain prefix’, for example: samples.flutter.dev/battery.

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class _MyHomePageState extends State<MyHomePage> {
  static const platform = MethodChannel('samples.flutter.dev/battery');
  // Get battery level.

接下来，在方法通道上调用方法（指定通过 String 标识符 getBatteryLevel 调用的具体方法）。调用可能会失败—比如，如果平台不支持此平台 API（比如在模拟器中运行），所以将 invokeMethod 调用包裹在 try-catch 语句中。

Next, invoke a method on the method channel, specifying the concrete method to call using the String identifier getBatteryLevel. The call might fail—for example if the platform does not support the platform API (such as when running in a simulator), so wrap the invokeMethod call in a try-catch statement.

在 setState 中使用返回结果来更新 _batteryLevel 内的用户界面状态。

Use the returned result to update the user interface state in _batteryLevel inside setState.

// Get battery level.
String _batteryLevel = 'Unknown battery level.';

Future<void> _getBatteryLevel() async {
  String batteryLevel;
  try {
    final int result = await platform.invokeMethod('getBatteryLevel');
    batteryLevel = 'Battery level at $result % .';
  } on PlatformException catch (e) {
    batteryLevel = "Failed to get battery level: '${e.message}'.";
  }

  setState(() {
    _batteryLevel = batteryLevel;
  });
}

最后，将模板中的 build 方法替换为包含以字符串形式显示电池状态、并包含一个用于刷新该值的按钮的小型用户界面。

Finally, replace the build method from the template to contain a small user interface that displays the battery state in a string, and a button for refreshing the value.

@override
Widget build(BuildContext context) {
  return Material(
    child: Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.spaceEvenly,
        children: [
          ElevatedButton(
            child: const Text('Get Battery Level'),
            onPressed: _getBatteryLevel,
          ),
          Text(_batteryLevel),
        ],
      ),
    ),
  );
}

步骤 3: 添加 Android 平台的实现

Step 3: Add an Android platform-specific implementation

Kotlin
Java

首先在 Android Studio 中打开 Flutter 应用的 Android 宿主部分：

Start by opening the Android host portion of your Flutter app in Android Studio:

启动 Android Studio
Start Android Studio
选择菜单项 File > Open…
Select the menu item File > Open…
导航到包含 Flutter 应用的目录，然后选择其中的 android 文件夹。点击 OK。
Navigate to the directory holding your Flutter app, and select the android folder inside it. Click OK.
在项目视图中打开 kotlin 文件夹下的 MainActivity.kt 文件（注意：如果使用 Android Studio 2.3 进行编辑，请注意 kotlin 目录的显示名称为 java）。
Open the file MainActivity.kt located in the kotlin folder in the Project view. (Note: If editing with Android Studio 2.3, note that the kotlin folder is shown as if named java.)

在 configureFlutterEngine() 方法中创建一个 MethodChannel 并调用 setMethodCallHandler()。确保使用的通道名称与 Flutter 客户端使用的一致。

Inside the configureFlutterEngine() method, create a MethodChannel and call setMethodCallHandler(). Make sure to use the same channel name as was used on the Flutter client side.

import androidx.annotation.NonNull
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel

class MainActivity: FlutterActivity() {
  private val CHANNEL = "samples.flutter.dev/battery"

  override fun configureFlutterEngine(@NonNull flutterEngine: FlutterEngine) {
    MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL).setMethodCallHandler {
      call, result ->
      // Note: this method is invoked on the main thread.
      // TODO
    }
  }
}

添加使用 Android battery API 来检索电池电量的 Android Kotlin 代码。该代码与你在原生 Android 应用中编写的代码完全相同。

Add the Android Kotlin code that uses the Android battery APIs to retrieve the battery level. This code is exactly the same as you would write in a native Android app.

首先在文件头部添加所需的依赖：

First, add the needed imports at the top of the file:

import android.content.Context
import android.content.ContextWrapper
import android.content.Intent
import android.content.IntentFilter
import android.os.BatteryManager
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES

然后在 MainActivity 类中的 configureFlutterEngine() 方法下方添加以下新方法：

Next, add the following method in the MainActivity class, below the configureFlutterEngine() method:

  private fun getBatteryLevel(): Int {
    val batteryLevel: Int
    if (VERSION.SDK_INT >= VERSION_CODES.LOLLIPOP) {
      val batteryManager = getSystemService(Context.BATTERY_SERVICE) as BatteryManager
      batteryLevel = batteryManager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY)
    } else {
      val intent = ContextWrapper(applicationContext).registerReceiver(null, IntentFilter(Intent.ACTION_BATTERY_CHANGED))
      batteryLevel = intent!!.getIntExtra(BatteryManager.EXTRA_LEVEL, -1) * 100 / intent.getIntExtra(BatteryManager.EXTRA_SCALE, -1)
    }

    return batteryLevel
  }

最后，完成前面添加的 onMethodCall() 方法。你需要处理单个平台方法 getBatteryLevel()，所以在参数 call 中对其进行验证。该平台方法的实现是调用上一步编写的 Android 代码，并使用 result 参数来返回成功和错误情况下的响应。如果调用了未知方法，则报告该方法。

Finally, complete the setMethodCallHandler() method added earlier. You need to handle a single platform method, getBatteryLevel(), so test for that in the call argument. The implementation of this platform method calls the Android code written in the previous step, and returns a response for both the success and error cases using the result argument. If an unknown method is called, report that instead.

删除以下代码：

Remove the following code:

    MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL).setMethodCallHandler {
      call, result ->
      // Note: this method is invoked on the main thread.
      // TODO
    }

并替换成以下内容：

And replace with the following:

    MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL).setMethodCallHandler {
      // Note: this method is invoked on the main thread.
      call, result ->
      if (call.method == "getBatteryLevel") {
        val batteryLevel = getBatteryLevel()

        if (batteryLevel != -1) {
          result.success(batteryLevel)
        } else {
          result.error("UNAVAILABLE", "Battery level not available.", null)
        }
      } else {
        result.notImplemented()
      }
    }

首先在 Android Studio 中打开 Flutter 应用的 Android 宿主部分：

Start by opening the Android host portion of your Flutter app in Android Studio:

启动 Android Studio
Start Android Studio
选择菜单项 File > Open…
Select the menu item File > Open…
导航到包含 Flutter 应用的目录，然后选择其中的 android 文件夹。点击 OK。
Navigate to the directory holding your Flutter app, and select the android folder inside it. Click OK.
在项目视图中打开 java 文件夹下的 MainActivity.java 文件。
Open the MainActivity.java file located in the java folder in the Project view.

接下来，在 configureFlutterEngine() 方法中创建一个 MethodChannel 并设置一个 MethodCallHandler。确保使用的通道名称与 Flutter 客户端使用的一致。

Next, create a MethodChannel and set a MethodCallHandler inside the configureFlutterEngine() method. Make sure to use the same channel name as was used on the Flutter client side.

import androidx.annotation.NonNull;
import io.flutter.embedding.android.FlutterActivity;
import io.flutter.embedding.engine.FlutterEngine;
import io.flutter.plugin.common.MethodChannel;

public class MainActivity extends FlutterActivity {
  private static final String CHANNEL = "samples.flutter.dev/battery";

  @Override
  public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
  super.configureFlutterEngine(flutterEngine);
    new MethodChannel(flutterEngine.getDartExecutor().getBinaryMessenger(), CHANNEL)
        .setMethodCallHandler(
          (call, result) -> {
            // Note: this method is invoked on the main thread.
            // TODO
          }
        );
  }
}

添加使用 Android battery API 来检索电池电量的 Android Java 代码。该代码与你在原生 Android 应用中编写的代码完全相同。

Add the Android Java code that uses the Android battery APIs to retrieve the battery level. This code is exactly the same as you would write in a native Android app.

首先在文件头部添加所需的依赖：

First, add the needed imports at the top of the file:

import android.content.ContextWrapper;
import android.content.Intent;
import android.content.IntentFilter;
import android.os.BatteryManager;
import android.os.Build.VERSION;
import android.os.Build.VERSION_CODES;
import android.os.Bundle;

然后在 Activity 类中的 onCreate() 方法下方添加以下新方法：

Then add the following as a new method in the activity class, below the configureFlutterEngine() method:

  private int getBatteryLevel() {
    int batteryLevel = -1;
    if (VERSION.SDK_INT >= VERSION_CODES.LOLLIPOP) {
      BatteryManager batteryManager = (BatteryManager) getSystemService(BATTERY_SERVICE);
      batteryLevel = batteryManager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY);
    } else {
      Intent intent = new ContextWrapper(getApplicationContext()).
          registerReceiver(null, new IntentFilter(Intent.ACTION_BATTERY_CHANGED));
      batteryLevel = (intent.getIntExtra(BatteryManager.EXTRA_LEVEL, -1) * 100) /
          intent.getIntExtra(BatteryManager.EXTRA_SCALE, -1);
    }

    return batteryLevel;
  }

最后，完成前面添加的 onMethodCall() 方法，你需要处理单个平台方法 getBatteryLevel()，所以在参数 call 中对其进行验证。该平台方法的实现是调用上一步编写的 Android 代码，并使用 result 参数来返回成功和错误情况下的响应。如果调用了未知方法，则报告该方法。

移除以下代码：

Remove the following code:

          (call, result) -> {
            // Note: this method is invoked on the main thread.
            // TODO
          }

并替换成以下内容：

And replace with the following:

          (call, result) -> {
            // Note: this method is invoked on the main thread.
            if (call.method.equals("getBatteryLevel")) {
              int batteryLevel = getBatteryLevel();

              if (batteryLevel != -1) {
                result.success(batteryLevel);
              } else {
                result.error("UNAVAILABLE", "Battery level not available.", null);
              }
            } else {
              result.notImplemented();
            }
          }

现在你应该可以在 Android 中运行该应用。如果使用了 Android 模拟器，请在扩展控件面板中设置电池电量，可从工具栏中的 … 按钮访问。

You should now be able to run the app on Android. If using the Android Emulator, set the battery level in the Extended Controls panel accessible from the … button in the toolbar.

步骤 4a：添加 iOS 平台的实现

Step 4a: Add an iOS platform-specific implementation

Objective-C
Swift

首先在 Xcode 中打开 Flutter 应用的 iOS 宿主部分：

Start by opening the iOS host portion of the Flutter app in Xcode:

启动 Xcode
Start Xcode.
选择菜单项 File > Open…
Select the menu item File > Open….
导航到包含 Flutter 应用的目录，然后选择其中的 ios 文件夹。点击 OK。
Navigate to the directory holding your Flutter app, and select the ios folder inside it. Click OK.
确保 Xcode 项目构建没有错误。
Make sure the Xcode projects builds without errors.
打开项目导航 Runner > Runner 下的 AppDelegate.m 文件。
Open the file AppDelegate.m, located under Runner > Runner in the Project navigator.

在 application didFinishLaunchingWithOptions: 方法中创建一个 FlutterMethodChannel 并添加一个处理程序。确保使用的通道名称与 Flutter 客户端使用的一致。

Create a FlutterMethodChannel and add a handler inside the application didFinishLaunchingWithOptions: method. Make sure to use the same channel name as was used on the Flutter client side.

#import <Flutter/Flutter.h>
#import "GeneratedPluginRegistrant.h"

@implementation AppDelegate
- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
  FlutterViewController* controller = (FlutterViewController*)self.window.rootViewController;

  FlutterMethodChannel* batteryChannel = [FlutterMethodChannel
                                          methodChannelWithName:@"samples.flutter.dev/battery"
                                          binaryMessenger:controller.binaryMessenger];

  [batteryChannel setMethodCallHandler:^(FlutterMethodCall* call, FlutterResult result) {
    // Note: this method is invoked on the UI thread.
    // TODO
  }];

  [GeneratedPluginRegistrant registerWithRegistry:self];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

接下来添加使用 iOS battery API 来检索电池电量的 iOS Objective-C 代码。该代码与你在原生 iOS 应用中编写的代码完全相同。

Next, add the iOS ObjectiveC code that uses the iOS battery APIs to retrieve the battery level. This code is exactly the same as you would write in a native iOS app.

在 AppDelegate 类中的 @end 之前添加以下方法：

Add the following method in the AppDelegate class, just before @end:

- (int)getBatteryLevel {
  UIDevice* device = UIDevice.currentDevice;
  device.batteryMonitoringEnabled = YES;
  if (device.batteryState == UIDeviceBatteryStateUnknown) {
    return -1;
  } else {
    return (int)(device.batteryLevel * 100);
  }
}

最后，完成前面添加的 setMethodCallHandler() 方法。你需要处理单个平台方法 getBatteryLevel()，所以在参数call 中对其进行验证。该平台方法的实现是调用上一步编写的 iOS 代码，并使用 result 参数来返回成功和错误情况下的响应。如果调用了未知方法，则报告该方法。

Finally, complete the setMethodCallHandler() method added earlier. You need to handle a single platform method, getBatteryLevel(), so test for that in the call argument. The implementation of this platform method calls the iOS code written in the previous step, and returns a response for both the success and error cases using the result argument. If an unknown method is called, report that instead.

__weak typeof(self) weakSelf = self;
[batteryChannel setMethodCallHandler:^(FlutterMethodCall* call, FlutterResult result) {
  // Note: this method is invoked on the UI thread.
  if ([@"getBatteryLevel" isEqualToString:call.method]) {
    int batteryLevel = [weakSelf getBatteryLevel];

    if (batteryLevel == -1) {
      result([FlutterError errorWithCode:@"UNAVAILABLE"
                                 message:@"Battery info unavailable"
                                 details:nil]);
    } else {
      result(@(batteryLevel));
    }
  } else {
    result(FlutterMethodNotImplemented);
  }
}];

现在你应该可以在 iOS 中运行该应用。如果使用了 iOS 模拟器，注意它并不支持 battery API，并且应用会显示 ‘battery info unavailable’。

You should now be able to run the app on iOS. If using the iOS Simulator, note that it does not support battery APIs, and the app displays ‘battery info unavailable’.

步骤 4b：使用 Swift 添加 iOS 平台的实现

Step 4b: Add an iOS platform-specific implementation using Swift

注意：以下步骤与 4a 类似，唯一的区别是使用了 Swift 而非 Objective-C。

Note: The following steps are similar to step 4a, only using Swift rather than Objective-C.

此步骤假设你在第一步中使用 -i swift 选项创建了项目。

This step assumes that you created your project in step 1. using the -i swift option.

首先在 Xcode 中打开 Flutter 应用的 iOS 宿主部分：

Start by opening the iOS host portion of your Flutter app in Xcode:

启动 Xcode
Start Xcode.
选择菜单项 File > Open…
Select the menu item File > Open….
导航到包含 Flutter 应用的目录，然后选择其中的 ios 文件夹。点击 OK。
Navigate to the directory holding your Flutter app, and select the ios folder inside it. Click OK.

在使用 Objective-C 的标准模板设置中添加对 Swift 的支持：

Add support for Swift in the standard template setup that uses Objective-C:

在项目导航中展开 Expand Runner > Runner。
Expand Runner > Runner in the Project navigator.
打开项目导航 Runner > Runner 下的 AppDelegate.swift 文件。
Open the file AppDelegate.swift located under Runner > Runner in the Project navigator.

重写 application:didFinishLaunchingWithOptions: 方法并创建一个绑定了通道名称 samples.flutter.dev/battery 的 FlutterMethodChannel：

Override the application:didFinishLaunchingWithOptions: function and create a FlutterMethodChannel tied to the channel name samples.flutter.dev/battery:

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    let controller : FlutterViewController = window?.rootViewController as! FlutterViewController
    let batteryChannel = FlutterMethodChannel(name: "samples.flutter.dev/battery",
                                              binaryMessenger: controller.binaryMessenger)
    batteryChannel.setMethodCallHandler({
      (call: FlutterMethodCall, result: @escaping FlutterResult) -> Void in
      // Note: this method is invoked on the UI thread.
      // Handle battery messages.
    })

    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

接下来添加使用 iOS battery API 来检索电池电量的 iOS Swift 代码。该代码与你在原生 iOS 应用中编写的代码完全相同。

Next, add the iOS Swift code that uses the iOS battery APIs to retrieve the battery level. This code is exactly the same as you would write in a native iOS app.

在 AppDelegate.swift 末尾添加以下新方法：

Add the following as a new method at the bottom of AppDelegate.swift:

private func receiveBatteryLevel(result: FlutterResult) {
  let device = UIDevice.current
  device.isBatteryMonitoringEnabled = true
  if device.batteryState == UIDevice.BatteryState.unknown {
    result(FlutterError(code: "UNAVAILABLE",
                        message: "Battery info unavailable",
                        details: nil))
  } else {
    result(Int(device.batteryLevel * 100))
  }
}

最后，完成前面添加的 setMethodCallHandler() 方法。你需要处理单个平台方法 getBatteryLevel()，所以在参数 call 中对其进行验证。该平台方法的实现是调用上一步编写的 iOS 代码。如果调用了未知方法，则报告该方法。

Finally, complete the setMethodCallHandler() method added earlier. You need to handle a single platform method, getBatteryLevel(), so test for that in the call argument. The implementation of this platform method calls the iOS code written in the previous step. If an unknown method is called, report that instead.

batteryChannel.setMethodCallHandler({
  [weak self] (call: FlutterMethodCall, result: FlutterResult) -> Void in
  // Note: this method is invoked on the UI thread.
  guard call.method == "getBatteryLevel" else {
    result(FlutterMethodNotImplemented)
    return
  }
  self?.receiveBatteryLevel(result: result)
})

现在你应该可以在 iOS 中运行该应用。如果使用了 iOS 模拟器，注意它并不支持 battery API，并且应用会显示 ‘battery info unavailable’。

You should now be able to run the app on iOS. If using the iOS Simulator, note that it does not support battery APIs, and the app displays ‘battery info unavailable’.

通过 Pigeon 获得类型安全的通道

Typesafe platform channels via Pigeon

在之前的样例中，我们使用 MethodChannel 在 host 和 client 之间进行通信，然而这并不是类型安全的。为了正确通信，调用/接收消息取决于 host 和 client 声明相同的参数和数据类型。 Pigeon 包可以用作 MethodChannel 的替代品，它将生成以结构化类型安全方式发送消息的代码。

The previous example uses MethodChannel to communicate between the host and client which isn’t typesafe. Calling and receiving messages depends on the host and client declaring the same arguments and datatypes in order for messages to work. The Pigeon package can be used as an alternative to MethodChannel to generate code that sends messages in a structured typesafe manner.

在 Pigeon 中，消息接口在 Dart 中进行定义，然后它将生成对应的 Android 以及 iOS 的代码。更复杂的例子以及更多信息尽在 Pigeon pub.dev page。

With Pigeon the messaging protocol is defined in a subset of Dart which then generates messaging code for Android or iOS. A more complete example and more information can be found on the Pigeon pub.dev page;

使用 Pigeon 消除了在主机和客户端之间匹配字符串的需要消息的名称和数据类型。它支持：嵌套类，消息转换为 API，生成异步包装代码并发送消息。生成的代码具有相当的可读性并保证在不同版本的多个客户端之间没有冲突。支持 Objective-C，Java，Kotlin 和 Swift（通过 Objective-C 互操作）语言。

Using Pigeon eliminates the need to match strings between host and client for the names and datatypes of messages. It supports: nested classes, grouping messages into APIs, generation of asynchronous wrapper code and sending messages in either direction. The generated code is readable and guarantees there will be no conflicts between multiple clients of different versions. Supported languages are Objective-C, Java, Kotlin and Swift (via Objective-C interop).

Pigeon 样例

Pigeon example

Pigeon file:

import 'package:pigeon/pigeon.dart';

class SearchRequest {
  String query = '';
}

class SearchReply {
  String result = '';
}

@HostApi()
abstract class Api {
  Future search(SearchRequest request);
}

Dart usage:

import 'generated_pigeon.dart';

void onClick() async {
  SearchRequest request = SearchRequest()..query = 'test';
  Api api = SomeApi();
  SearchReply reply = await api.search(request);
  print('reply: ${reply.result}');
}

从 UI 代码中分离平台相关代码

Separate platform-specific code from UI code

如果你想要在多个 Flutter 应用中使用你的平台相关代码，则将代码分离为位于主应用目录之外的平台插件会很有用。相关细节查看 Flutter Packages 的开发和提交。

If you expect to use your platform-specific code in multiple Flutter apps, it can be useful to separate the code into a platform plugin located in a directory outside your main application. See developing packages for details.

将平台相关代码作为 Package 进行提交

Publish platform-specific code as a package

与 Flutter 生态中的其他开发者共享你的平台相关代码，可查看提交 package。

To share your platform-specific code with other developers in the Flutter ecosystem, see publishing packages.

自定义通道和编解码器

Custom channels and codecs

除了上面提到的 MethodChannel，你还可以使用更基础的 BasicMessageChannel，它支持使用自定义的消息编解码器进行基本的异步消息传递。你还可以使用专门的 BinaryCodec、StringCodec 和 JSONMessageCodec 类，或创建自己的编解码器。

Besides the above mentioned MethodChannel, you can also use the more basic BasicMessageChannel, which supports basic, asynchronous message passing using a custom message codec. You can also use the specialized BinaryCodec, StringCodec, and JSONMessageCodec classes, or create your own codec.

您还可以在 cloud_firestore 插件中查看自定义编解码器的示例，该插件可以序列化和反序列化比默认类型更多的类型。

You might also check out an example of a custom codec in the cloud_firestore plugin, which is able to serialize and deserialize many more types than the default types.

通道和平台线程

Channels and Platform Threading

目标平台向 Flutter 发起 channel 调用的时候，需要在对应平台的主线程执行。同样的，在 Flutter 向目标平台发起 channel 调用的时候，需要在根 Isolate 中执行。对应平台侧的 handler 既可以在平台的主线程执行，也可以通过事件循环在后台执行。对应平台侧 handler 的返回值可以在任意线程异步执行。

When invoking channels on the platform side destined for Flutter, they need to be invoked on the platform’s main thread. When invoking channels in Flutter destined for the platform side, they need to be invoked on the root Isolate. The platform side’s handlers can execute on the platform’s main thread or they can execute on a background thread if a Task Queue is used. The result of the platform side handlers can be invoked asynchronously and on any thread.

提示

在 Android 平台上时，平台的 main 线程有时候被叫做主线程，但是它在技术上被看作 UI 线程。被 @UiThread 注解标记的方法需要在 UI 线程上执行。在 iOS 上，这个线程被官方标记为主线程。

On Android, the platform’s main thread is sometimes called the “main thread”, but it is technically defined as the UI thread. Annotate methods that need to be run on the UI thread with @UiThread. On iOS, this thread is officially referred to as the main thread.

在后台线程中执行 channel 的 handlers

Executing channel handlers on background threads

要在 channel 对应的平台侧的后台中执行 handler，需要使用 Task Queue API。当前该功能仅支持在 iOS 和 Android。

In order for a channel’s platform side handler to execute on a background thread, the Task Queue API has be used. Currently this feature is only supported on iOS and Android.

对应的 Java 代码：

In Java:

@Override
public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
  BinaryMessenger messenger = binding.getBinaryMessenger();
  BinaryMessenger.TaskQueue taskQueue =
      messenger.makeBackgroundTaskQueue();
  channel =
      new MethodChannel(
          messenger,
          "com.example.foo",
          StandardMethodCodec.INSTANCE,
          taskQueue);
  channel.setMethodCallHandler(this);
}

Kotlin 版本：

In Kotlin:

override fun onAttachedToEngine(@NonNull flutterPluginBinding: FlutterPlugin.FlutterPluginBinding) {
  val taskQueue =
      flutterPluginBinding.binaryMessenger.makeBackgroundTaskQueue()
  channel = MethodChannel(flutterPluginBinding.binaryMessenger,
                          "com.example.foo",
                          StandardMethodCodec.INSTANCE,
                          taskQueue)
  channel.setMethodCallHandler(this)
}

Swift 版本：

In Swift:

public static func register(with registrar: FlutterPluginRegistrar) {
  let taskQueue = registrar.messenger.makeBackgroundTaskQueue()
  let channel = FlutterMethodChannel(name: "com.example.foo",
                                     binaryMessenger: registrar.messenger(),
                                     codec: FlutterStandardMethodCodec.sharedInstance,
                                     taskQueue: taskQueue)
  let instance = MyPlugin()
  registrar.addMethodCallDelegate(instance, channel: channel)
}

Objective-C 版本：

In Objective-C:

+ (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar {
  NSObject<FlutterTaskQueue>* taskQueue =
      [[registrar messenger] makeBackgroundTaskQueue];
  FlutterMethodChannel* channel =
      [FlutterMethodChannel methodChannelWithName:@"com.example.foo"
                                  binaryMessenger:[registrar messenger]
                                            codec:[FlutterStandardMethodCodec sharedInstance]
                                        taskQueue:taskQueue];
  MyPlugin* instance = [[MyPlugin alloc] init];
  [registrar addMethodCallDelegate:instance channel:channel];
}

跳转到 Android 中的 UI 线程

Jumping to the UI thread in Android

为了符合通道跳转到 Android UI 线程的要求，你可能需要从后台线程跳转到 Android 的 UI 线程以执行通道的方法。在 Android 中的实现方式是：在一个叫 Looper 的 Android UI 线程里 post() 一个 Runnable。这能使得 Runnable 在下一次机会时在主线程上执行。

To comply with channels’ UI thread requirement, you may need to jump from a background thread to Android’s UI thread to execute a channel method. In Android this is accomplished by post()ing a Runnable to Android’s UI thread Looper, which causes the Runnable to execute on the main thread at the next opportunity.

Java 代码：

In Java:

new Handler(Looper.getMainLooper()).post(new Runnable() {
  @Override
  public void run() {
    // Call the desired channel message here.
  }
});

Kotlin 代码：

In Kotlin:

Handler(Looper.getMainLooper()).post {
  // Call the desired channel message here.
}

跳转到 iOS 中的主线程

Jumping to the main thread in iOS

为了符合通道跳转到 iOS 主线程的要求，您可能需要从后台线程跳转到 iOS 的主线程来执行通道方法。在iOS中，这是通过在主 dispatch queue上执行 block来实现的：

To comply with channel’s main thread requirement, you may need to jump from a background thread to iOS’s main thread to execute a channel method. In iOS this is accomplished by executing a block on the main dispatch queue:

Objective-C 代码：

In Objective-C:

dispatch_async(dispatch_get_main_queue(), ^{
  // Call the desired channel message here.
});

Swift 代码：

In Swift:

DispatchQueue.main.async {
  // Call the desired channel message here.
}

在 Flutter 里使用 Packages

使用 package
Using packages
开发新的 package
Developing new packages
管理 package 的依赖和版本
Managing package dependencies and versions
例子
Examples
- 例子：使用 CSS Colors package
  Example: Using the CSS Colors package
- 例子：使用 url_launcher package 来打开浏览器
  Example: Using the url_launcher package to launch the browser

Flutter 支持使用其他开发者向 Flutter 和 Dart 生态系统贡献的共享 package，这意味着你可以快速构建应用而不是一切从零开始。

Flutter supports using shared packages contributed by other developers to the Flutter and Dart ecosystems. This allows quickly building an app without having to develop everything from scratch.

Package 和插件 (plugin) 有什么区别呢？ 插件 (plugin) 是 package 的一种，全称是 plugin package，我们简称为 plugin，中文叫插件。

What is the difference between a package and a plugin? A plugin is a type of package—the full designation is plugin package, which is generally shortened to plugin.

Packages
Dart package 最低要求是包含一个 pubspec.yaml 文件。此外，一个 package 可以包含依赖关系 (在 pubspec.yaml 文件里声明)、 Dart 库、应用、资源、测试、图片和例子等。 pub.dev 上列出了很多 package，由 Google 工程师和 Flutter 和 Dart 社区的开发者开发和发布，你可以用在自己的应用里。

Packages
At a minimum, a Dart package is a directory containing a pubspec file. Additionally, a package can contain dependencies (listed in the pubspec), Dart libraries, apps, resources, tests, images, and examples. The pub.dev site lists many packages—developed by Google engineers and generous members of the Flutter and Dart community— that you can use in your app.

Plugins
插件 (plugin package) 是一种特别的 package，特别指那些帮助你获得原生平台特性的 package。插件可以为 Android (使用 Kotlin 或 Java 语言)、 iOS (使用 Swift 或 Objective-C 语言)、Web、macOS、Windows、Linux 平台，或其任意组合的平台编写。比如：某个插件可以为 Flutter 应用提供使用原生平台的摄像头的功能。

Plugins
A plugin package is a special kind of package that makes platform functionality available to the app. Plugin packages can be written for Android (using Kotlin or Java), iOS (using Swift or Objective-C), web, macOS, Windows, Linux, or any combination thereof. For example, a plugin might provide Flutter apps with the ability to use a device’s camera.

现有的 package 支持许多使用场景，例如，网络请求 (http)，自定义导航/路由处理 (fluro)，集成设备 API（如 (url_launcher 和 battery，以及使用第三方平台的 SDK（如 Firebase 的 (FlutterFire)。

Existing packages enable many use cases—for example, making network requests (http), custom navigation/route handling (fluro), integration with device APIs (url_launcher and battery), and using third-party platform SDKs like Firebase (FlutterFire).

如果你正打算开发新的 package，请参阅 Flutter Packages 的开发和提交。

To write a new package, see developing packages.

如果你想添加资源、图片或字体，无论是存储在文件中还是 package 中，请参阅添加资源和图片这篇文档。

To add assets, images or fonts, whether stored in files or packages, see Adding assets and images.

使用 package

Using packages

下面的内容将为你描述如何使用已经发布了的 packages。

The following section describes how to use existing published packages.

搜索 package

Searching for packages

Package 会被发布到 pub.dev 网站上。

Packages are published to pub.dev.

Pub 网站上的 Flutter 页面展示了与 Flutter 兼容的 package（即声明的依赖通常与 Flutter 兼容），并且所有已发布的 package 都支持搜索。

The Flutter landing page on pub.dev displays top packages that are compatible with Flutter (those that declare dependencies generally compatible with Flutter), and supports searching among all published packages.

Pub.dev 上的 Flutter Favorites 页面列出了一系列编写应用时可以首先考虑使用的插件和 package，关于这个项目的更多信息，请查看 Flutter Favorites 项目页面。

The Flutter Favorites page on pub.dev lists the plugins and packages that have been identified as packages you should first consider using when writing your app. For more information on what it means to be a Flutter Favorite, see the Flutter Favorites program.

在 pub.dev 网站上同时可以过滤出适合 Android、iOS 或 Web 的插件，也可以通过复选框，过滤出组合结果（适配一个或者多个平台）。

You can also browse the packages on pub.dev by filtering on Android plugins, iOS plugins, web plugins, or any combination thereof.

将 package 依赖添加到应用

Adding a package dependency to an app

要将 package ‘css_colors’ 添加到应用：

To add the package, css_colors, to an app:

添加依赖
Depend on it
- 打开应用文件夹下的 pubspec.yaml 文件，然后在 pubspec.yaml 下添加 css_colors:。
  Open the pubspec.yaml file located inside the app folder, and add css_colors: under dependencies.
安装
Install it
- 在命令行中运行：flutter pub get
  From the terminal: Run flutter pub get
或者
OR
- 在 Android Studio/IntelliJ 中点击 pubspec.yaml 文件顶部操作功能区的 Packages get
  From Android Studio/IntelliJ: Click Packages get in the action ribbon at the top of pubspec.yaml.
- 在 VS Code 中点击位于 pubspec.yaml 文件顶部操作功能区右侧的 Get Packages
  From VS Code: Click Get Packages located in right side of the action ribbon at the top of pubspec.yaml.
导入
Import it
- 在 Dart 代码中添加相关的 import 语句。
  Add a corresponding import statement in the Dart code.
如果有必要，停止并重启应用
Stop and restart the app, if necessary
- 如果 package 内有特定平台的代码（Android 的 Java/Kotlin, iOS 的 Swift/Objective-C），代码必须内置到你的应用内。热重载和热重启只对 package 的 Dart 代码执行此操作，所以你需要完全重启应用以避免使用 package 时出现 MissingPluginException 错误。
  If the package brings platform-specific code (Kotlin/Java for Android, Swift/Objective-C for iOS), that code must be built into your app. Hot reload and hot restart only update the Dart code, so a full restart of the app might be required to avoid errors like MissingPluginException when using the package.

对于这些步骤，Pub 上任何 package 页面的 Installing tab 选项卡都是一个很方便的参考。

The Installing tab, available on any package page on pub.dev, is a handy reference for these steps.

完整示例，参阅下面的 css_colors 示例。

For a complete example, see the css_colors example below.

冲突解决

Conflict resolution

假设你想在应用中使用 some_package 和 other_package，并且它们依赖于不同版本的 url_launcher。于是我们便有了潜在的冲突。避免这种情况的最好方法是 package 的作者在指定依赖项时使用版本范围而非特定版本。

Suppose you want to use some_package and another_package in an app, and both of these depend on url_launcher, but in different versions. That causes a potential conflict. The best way to avoid this is for package authors to use version ranges rather than specific versions when specifying dependencies.

dependencies:
  url_launcher: ^5.4.0    # Good, any version >= 5.4.0 but < 6.0.0
  image_picker: '5.4.3'   # Not so good, only version 5.4.3 works.

如果 some_package 声明了以上依赖，并且 another_package 声明了一个兼容的 url_launcher 依赖项，如 '5.4.6' 或 ^5.5.0， pub 能够自动解决冲突问题。 Gradle modules 和 CocoaPods 也是用类似的方式解决平台依赖的。

If some_package declares the dependencies above and another_package declares a compatible url_launcher dependency like '5.4.6' or ^5.5.0, pub resolves the issue automatically. Platform-specific dependencies on Gradle modules and/or CocoaPods are solved in a similar way.

即使 some_package 和 another_package 声明了不兼容的 url_launcher 版本，它们实际上仍可能以兼容的方式使用 url_launcher。在这种情况下，可在 pubspec.yaml 文件中添加一个依赖覆盖声明来强制使用特定版本，从而处理冲突。

Even if some_package and another_package declare incompatible versions for url_launcher, they might actually use url_launcher in compatible ways. In this situation, the conflict can be resolved by adding a dependency override declaration to the app’s pubspec.yaml file, forcing the use of a particular version.

为了强制使用版本为 5.4.0 的 url_launcher，你可以对应用的 pubspec.yaml 文件做如下更改：

For example, to force the use of url_launcher version 5.4.0, make the following changes to the app’s pubspec.yaml file:

dependencies:
  some_package:
  another_package:
dependency_overrides:
  url_launcher: '5.4.0'

如果依赖冲突项不是 package 自身，而是如 guava 这样特定于 Android 的库，那么依赖的覆盖声明必须添加到 Gradle 的构建逻辑中。

If the conflicting dependency is not itself a package, but an Android-specific library like guava, the dependency override declaration must be added to Gradle build logic instead.

为了强制使用版本为 28.0 的 guava，你可以对 android/build.gradle 文件做如下更改：

To force the use of guava version 28.0, make the following changes to the app’s android/build.gradle file:

configurations.all {
    resolutionStrategy {
        force 'com.google.guava:guava:28.0-android'
    }
}

CocoaPods 目前尚不提供依赖项覆盖功能。

CocoaPods does not currently offer dependency override functionality.

开发新的 package

Developing new packages

如果某个 package 不适用于你的特定需求，你可以开发新的自定义 package。

If no package exists for your specific use case, you can write a custom package.

管理 package 的依赖和版本

Managing package dependencies and versions

为了使版本冲突的风险最小化，请在 pubspec.yaml 文件中指定一个版本范围。

To minimize the risk of version collisions, specify a version range in the pubspec.yaml file.

Package 版本

Package versions

所有 package 都有一个版本号，在它们的 pubspec.yaml 文件中指定。当前的 package 版本会在其名称旁边显示当前版本号。（例如，参阅 url_launcher package）以及所有先前版本的列表： url_launcher 版本列表。

All packages have a version number, specified in the package’s pubspec.yaml file. The current version of a package is displayed next to its name (for example, see the url_launcher package), as well as a list of all prior versions (see url_launcher versions).

当使用简写形式 plugin1: 将 package 添加到 pubspec.yaml 时，表明 plugin1 package 的任何版本都可以被使用。为了确保在更新 package 的时候你的应用不会崩溃，我们建议使用以下格式之一来指定版本范围：

When a package is added to pubspec.yaml, the shorthand form plugin1: means that any version of the plugin1 package can be used. To ensure that the app doesn’t break when a package is updated, specify a version range using one of the following formats:

范围限制：指定一个最小和最大的版本号，例如：
Range constraints: Specify a minimum and maximum version. For example:
```
dependencies:
 url_launcher: '>=5.4.0 <6.0.0'
```
使用 caret语法 的范围约束与常规的范围约束类似：
Range constraints with caret syntax are similar to regular range constraints:
```
dependencies:
  collection: '^5.4.0'
```

了解更详细的信息，参阅 Pub 版本管理指南。

For additional details, see the package versioning guide.

更新 package 依赖

Updating package dependencies

当你添加一个 package 后首次运行 flutter pub get（IntelliJ 或 Android Studio 中的 Packages Get）， Flutter 将会保存在 pubspec.lock lockfile 中找到的具体 package 版本。这将确保当你或者团队中其他开发者运行 flutter pub get 后能得到相同版本的 package。

When running flutter pub get (Packages get in IntelliJ or Android Studio) for the first time after adding a package, Flutter saves the concrete package version found in the pubspec.lock lockfile. This ensures that you get the same version again if you, or another developer on your team, run flutter pub get.

如果你想升级到 package 的最新版本，比如使用 package 的最新特性，请运行 flutter packages upgrade （IntelliJ 或 Android Studio 的 Upgrade dependencies 功能）。这将检索你在 pubspec.yaml 文件中指定的版本约束所允许的最高可用版本。请注意，flutter upgrade 与 flutter update-packages 是两个不同的命令，但它们都会更新 Flutter。

To upgrade to a new version of the package, for example to use new features in that package, run flutter pub upgrade (Upgrade dependencies in IntelliJ or Android Studio) to retrieve the highest available version of the package that is allowed by the version constraint specified in pubspec.yaml. Note that this is a different command from flutter upgrade or flutter update-packages, which both update Flutter itself.

依赖未发布的 package

Dependencies on unpublished packages

即使未在 Pub site 上发布，也可以使用 package。对于不用于公开发布的私有插件，或者尚未准备好发布的 package，可以使用其他依赖选项。

Packages can be used even when not published on pub.dev. For private plugins, or for packages not ready for publishing, additional dependency options are available:

Path 依赖
Flutter 应用可以通过文件系统 path: 依赖而依赖于插件。路径可以是相对的，也可以是绝对的。例如，要依赖位于应用相邻目录中的插件 plugin1，可以使用以下语法：

Path dependency
A Flutter app can depend on a plugin via a file system path: dependency. The path can be either relative or absolute. Relative paths are evaluated relative to the directory containing pubspec.yaml. For example, to depend on a plugin plugin1 located in a directory next to the app, use the following syntax:

  dependencies:
    plugin1:
      path: ../plugin1/

Git 依赖
你也可以依赖存储在 Git 仓库中的 package，如果 package 位于仓库的根目录，可以使用以下语法：

Git dependency
You can also depend on a package stored in a Git repository. If the package is located at the root of the repo, use the following syntax:

  dependencies:
    plugin1:
      git:
        url: git://github.com/flutter/plugin1.git

**Git 依赖于文件夹中的 package **
默认情况下，pub 会默认假定 package 位于 Git 仓库的根目录。如果不是这种情况，你可以使用 path 参数指定位置，例如：

Git dependency on a package in a folder
Pub assumes the package is located in the root of the Git repository. If that is not the case, specify the location with the path argument. For example:

  dependencies:
    package1:
      git:
        url: git://github.com/flutter/packages.git
        path: packages/package1

最后，你可以使用 ref 参数将依赖固定到 git 特定的 commit、branch 或者 tag。更多详细信息，请参阅 Package dependencies。

Finally, use the ref argument to pin the dependency to a specific git commit, branch, or tag. For more details, see Package dependencies.

例子

Examples

下面的示例将介绍使用 packages 的一些必要步骤。

The following examples walk through the necessary steps for using packages.

例子：使用 CSS Colors package

Example: Using the CSS Colors package

css_colors package 为 CSS 颜色定义颜色常量，允许你在 Flutter 框架中任何需要 Color 类型的地方使用它们。

The css_colors package defines color constants for CSS colors, so use the constants wherever the Flutter framework expects the Color type.

要使用这个 package：

To use this package:

创建一个名为 cssdemo 的新项目
Create a new project called cssdemo.

打开 pubspec.yaml，并添加依赖 css-colors：

Open pubspec.yaml, and add the css-colors dependency:

dependencies:
  flutter:
    sdk: flutter

替换为：

with:

dependencies:
  flutter:
    sdk: flutter
  css_colors: ^1.0.0

在命令行中运行 flutter packages get，或者点击 Intellij 中的 Packages get
Run flutter pub get in the terminal, or click Packages get in IntelliJ or Android Studio.

打开 lib/main.dart 并将其全部内容替换为：

Open lib/main.dart and replace its full contents with:

import 'package:css_colors/css_colors.dart';
 import 'package:flutter/material.dart';

 void main() {
   runApp(const MyApp());
 }

 class MyApp extends StatelessWidget {
   const MyApp({Key? key}) : super(key: key);

   @override
   Widget build(BuildContext context) {
     return const MaterialApp(
       home: DemoPage(),
     );
   }
 }

 class DemoPage extends StatelessWidget {
   const DemoPage({Key? key}) : super(key: key);

   @override
   Widget build(BuildContext context) {
     return Scaffold(body: Container(color: CSSColors.orange));
   }
 }

运行应用。当你点击 ‘Show Flutter homepage’ 时，你将看到手机默认浏览器打开并出现 Flutter 主页。
Run the app. The app’s background should now be orange.

例子：使用 url_launcher package 来打开浏览器

Example: Using the url_launcher package to launch the browser

url_launcher 插件可以让你在移动平台上打开默认浏览器以显示给定的 URL。它演示了 package 如何也可能包含特定于平台的代码我们将这一类包含各平台不同代码的 package 称为 插件 package 或者插件。

The url_launcher plugin package enables opening the default browser on the mobile platform to display a given URL, and is supported on Android, iOS, web, and macos. This package is a special Dart package called a plugin package (or plugin), which includes platform-specific code.

要使用这个插件：

To use this plugin:

新建一个名为 lauchdemo 的新项目；
Create a new project called launchdemo.
打开 pubspec.yaml，然后添加 url_launcher 的依赖：
Open pubspec.yaml, and add the url_launcher dependency:
```
dependencies:
  flutter:
    sdk: flutter
  url_launcher: ^5.4.0
```
在命令行中运行 flutter packages get，或者点击 Intellij 或 Android Studio 中的 Packages get；
Run flutter pub get in the terminal, or click Packages get in IntelliJ or Android Studio.

打开 lib/main.dart 并将其全部内容替换为：

Open lib/main.dart and replace its full contents with the following:

import 'package:flutter/material.dart';
 import 'package:url_launcher/url_launcher.dart';

 void main() {
   runApp(const MyApp());
 }

 class MyApp extends StatelessWidget {
   const MyApp({Key? key}) : super(key: key);

   @override
   Widget build(BuildContext context) {
     return const MaterialApp(
       home: DemoPage(),
     );
   }
 }

 class DemoPage extends StatelessWidget {
   const DemoPage({Key? key}) : super(key: key);

   launchURL() {
     launch('https://flutter.dev');
   }

   @override
   Widget build(BuildContext context) {
     return Scaffold(
       body: Center(
         child: ElevatedButton(
           onPressed: launchURL,
           child: const Text('Show Flutter homepage'),
         ),
       ),
     );
   }
 }

运行应用（如果你的应用在添加插件之前已经运行，请停止并重启应用）。当你点击 Show Flutter homepage 时，你将看到手机默认浏览器打开并出现 Flutter 主页。
Run the app (or stop and restart it, if it was already running before adding the plugin). Click Show Flutter homepage. You should see the default browser open on the device, displaying the homepage for flutter.dev.

Flutter Packages 的开发和提交

Package 介绍
Package introduction
- Package 类别
  Package types
开发纯 Dart 的 packages
Developing Dart packages
- 第一步：创建 package
  Step 1: Create the package
- 第二步：实现 package
  Step 2: Implement the package
开发原生插件类型的 packages
Developing plugin packages
添加文档
Adding documentation
- API 文档
  API documentation
- 将许可证添加到 LICENSE 文件中
  Adding licenses to the LICENSE file
提交 package
Publishing your package
Package 依赖处理
Handling package interdependencies
- Android
- iOS
- Web

插件 API 现已支持联合插件，从而分离在不同平台上的实现。你可以指定哪些平台有插件支持，例如 Web 和 macOS。

The plugin API has been updated and now supports federated plugins that enable separation of different platform implementations. You can also now indicate which platforms a plugin supports, for example web and macOS.

旧的插件 API 会在将来被废弃。如果在短期内你仍在使用旧版本的插件 API，你会看到警告。想了解更多关于升级 Android 插件的内容，请阅读支持新的 Android 插件 API。

Eventually, the old plugin APIs will be deprecated. In the short term, you will see a warning when the framework detects that you are using an old-style plugin. For information on how to upgrade your plugin, see Supporting the new Android plugins APIs.

Package 介绍

Package introduction

通过使用 package（的模式）可以创建易于共享的模块化代码。一个最基本的 package 由以下内容构成：

Packages enable the creation of modular code that can be shared easily. A minimal package consists of the following:

pubspec.yaml 文件
用于定义 package 名称、版本号、作者等其他信息的元数据文件。

pubspec.yaml
A metadata file that declares the package name, version, author, and so on.

lib 目录
包含共享代码的 lib 目录，其中至少包含一个 <package-name>.dart 文件。

lib
The lib directory contains the public code in the package, minimally a single <package-name>.dart file.

Package 类别

Package types

Package 包含以下几种类别：

Packages can contain more than one kind of content:

纯 Dart 库 (Dart packages)
用 Dart 编写的传统 package，比如 path。其中一些可能包含 Flutter 的特定功能，因此依赖于 Flutter 框架，其使用范围仅限于 Flutter，比如 fluro。

Dart packages
General packages written in Dart, for example the path package. Some of these might contain Flutter specific functionality and thus have a dependency on the Flutter framework, restricting their use to Flutter only, for example the fluro package.

原生插件 (Plugin packages)
使用 Dart 编写的，按需使用 Java 或 Kotlin、Objective-C 或 Swift 分别在 Android 和/或 iOS 平台实现的 package。

Plugin packages
A specialized Dart package that contains an API written in Dart code combined with one or more platform-specific implementations.

插件 package 可以针对 Android（使用 Kotlin 或 Java）、 iOS（使用 Swift 或 Objective-C）、Web、macOS、Windows 或 Linux，又或者它们的各种组合方式，进行编写。

Plugin packages can be written for Android (using Kotlin or Java), iOS (using Swift or Objective-C), web, macOS, Windows, or Linux, or any combination thereof.

一个较为具体的实现例子是 url_launcher 插件 package。想了解如何使用 url_launcher package，以及它如何扩展 Web 的实现，请阅读 Medium 上由 Harry Terkelsen 撰写的文章如何编写 Flutter Web 插件，第一部分。

A concrete example is the url_launcher plugin package. To see how to use the url_launcher package, and how it was extended to implement support for web, see the Medium article by Harry Terkelsen, How to Write a Flutter Web Plugin, Part 1.

开发纯 Dart 的 packages

Developing Dart packages

下面会为你介绍如何写 Flutter package。

The following instructions explain how to write a Flutter package.

第一步：创建 package

Step 1: Create the package

想要创建纯 Dart 库的 package，请使用带有 --template=package 标志的 flutter create 命令：

To create a Flutter package, use the --template=package flag with flutter create:

$ flutter create --template=package hello

这将在 hello 目录下创建一个 package 项目，其中包含以下内容：

This creates a package project in the hello folder with the following content:

LICENSE 文件
大概率会是空的一个许可证文件。

LICENSE
A (mostly) empty license text file.

test/hello_test.dart 文件
Package 的单元测试文件。

test/hello_test.dart
The unit tests for the package.

hello.iml 文件
由 IntelliJ 生成的配置文件。

hello.iml
A configuration file used by the IntelliJ IDEs.

.gitignore 文件
告诉 Git 系统应该隐藏哪些文件或文件夹的一个隐藏文件。

.gitignore
A hidden file that tells Git which files or folders to ignore in a project.

.metadata 文件
IDE 用来记录某个 Flutter 项目属性的的隐藏文件。

.metadata
A hidden file used by IDEs to track the properties of the Flutter project.

pubspec.yaml 文件
pub 工具需要使用的，包含 package 依赖的 yaml 格式的文件。

pubspec.yaml
A yaml file containing metadata that specifies the package’s dependencies. Used by the pub tool.

README.md 文件
起步文档，用于描述 package。

README.md
A starter markdown file that briefly describes the package’s purpose.

lib/hello.dart 文件
package 的 Dart 实现代码。

lib/hello.dart
A starter app containing Dart code for the package.

.idea/modules.xml、.idea/workspace.xml 文件
IntelliJ 的各自配置文件（包含在 .idea 隐藏文件夹下）。

.idea/modules.xml, .idea/workspace.xml
A hidden folder containing configuration files for the IntelliJ IDEs.

CHANGELOG.md 文件
又一个大概率为空的文档，用于记录 package 的版本变更。

CHANGELOG.md
A (mostly) empty markdown file for tracking version changes to the package.

第二步：实现 package

Step 2: Implement the package

对于纯 Dart 库的 package，只要在 lib/<package name>.dart 文件中添加功能实现，或在 lib 目录中的多个文件中添加功能实现。

For pure Dart packages, simply add the functionality inside the main lib/<package name>.dart file, or in several files in the lib directory.

如果要对 package 进行测试，在 test 目录下添加单元测试。

To test the package, add unit tests in a test directory.

关于如何组织 package 内容的更多详细信息，请参考 Dart library package 文档。

For additional details on how to organize the package contents, see the Dart library package documentation.

开发原生插件类型的 packages

Developing plugin packages

如果想要开发一个调用特定平台 API 的 package，你需要开发一个原生插件 packgae。

If you want to develop a package that calls into platform-specific APIs, you need to develop a plugin package.

它的 API 通过平台通道连接到平台特定的实现。

The API is connected to the platform-specific implementation(s) using a platform channel.

联合插件

Federated plugins

Federated plugins (联合插件) 是一种将对不同平台的支持分为单独的软件包。所以，联合插件能够使用针对 iOS、Android、Web 甚至是针对汽车 (例如在 IoT 设备上)分别使用对应的 package。除了这些好处之外，它还能够让领域专家在他们最了解的平台上扩展现有平台插件。

Federated plugins are a way of splitting support for different platforms into separate packages. So, a federated plugin can use one package for iOS, another for Android, another for web, and yet another for a car (as an example of an IoT device). Among other benefits, this approach allows a domain expert to extend an existing plugin to work for the platform they know best.

联合插件需要以下 package：

A federated plugin requires the following packages:

面向应用的 package
该 package 是用户使用插件的的直接依赖。它指定了 Flutter 应用使用的 API。

app-facing package
The package that plugin users depend on to use the plugin. This package specifies the API used by the Flutter app.

平台 package
一个或多个包含特定平台代码的 package。面向应用的 package 会调用这些平台 package—— 除非它们带有一些终端用户需要的特殊平台功能，否则它们不会包含在应用中。

platform package(s)
One or more packages that contain the platform-specific implementation code. The app-facing package calls into these packages—they aren’t included into an app, unless they contain platform-specific functionality accessible to the end user.

平台接口 package
将面向应用的 package 与平台 package 进行整合的 package。该 package 会声明平台 package 需要实现的接口，供面向应用的 package 使用。使用单一的平台接口 package 可以确保所有平台 package 都按照各自的方法实现了统一要求的功能。

platform interface package
The package that glues the app-facing packing to the platform package(s). This package declares an interface that any platform package must implement to support the app-facing package. Having a single package that defines this interface ensures that all platform packages implement the same functionality in a uniform way.

整合的联合插件

Endorsed federated plugin

理想情况下，当你在为一个联合插件添加某个平台的实现时，你会与 package 的作者合作，将你的实现纳入 package。

Ideally, when adding a platform implementation to a federated plugin, you will coordinate with the package author to include your implementation. In this way, the original author endorses your implementation.

假设你开发了 foobar_windows 插件，用于对应 foobar 插件的实现。在整合的联合插件里，foobar 的原作者会将你的 Windows 实现作为依赖添加在 pubspec 文件中，供面向应用的 package 调用。而后在开发者使用 foobar 插件时，Windows 及已包含的其他平台的实现就自动可用了。

For example, say you write a foobar_windows implementation for the (imaginary) foobar plugin. In an endorsed plugin, the original foobar author adds your Windows implementation as a dependency in the pubspec for the app-facing package. Then, when a developer includes the foobar plugin in their Flutter app, the Windows implementation, as well as the other endorsed implementations, are automatically available to the app.

未整合的联合插件

Non-endorsed federated plugin

如果你的实现出于某些原因无法被原作者整合，那么你的插件属于 未整合 的联合插件。开发者仍然可以使用你的实现，但是必须手动在 pubspec 文件里添加引用。意味着开发者需要同时引用 foobar 和 foobar_windows 依赖，才能使用对应平台的完整功能。

If you can’t, for whatever reason, get your implementation added by the original plugin author, then your plugin is not endorsed. A developer can still use your implementation, but must manually add the plugin to the app’s pubspec file. So, the developer must include both the foobar dependency and the foobar_windows dependency in order to achieve full functionality.

有关联合插件的更多信息、它为什么非常强大，以及如何实现联合插件，你可以阅读 Harry Terkelsen 在 Medium 撰写的如何撰写 Flutter Web 插件，第 2 部分。

For more information on federated plugins, why they are useful, and how they are implemented, see the Medium article by Harry Terkelsen, How To Write a Flutter Web Plugin, Part 2.

指定一个插件支持的平台

Specifying a plugin’s supported platforms

插件可以通过向 pubspec.yaml 中的 platforms map 添加 keys 来指定其支持的平台。例如，以下是 hello 插件的 flutter: map，它仅支持 Android 和 iOS：

Plugins can specify the platforms they support by adding keys to the platforms map in the pubspec.yaml file. For example, the following pubspec file shows the flutter: map for the hello plugin, which supports only iOS and Android:

flutter:
  plugin:
    platforms:
      android:
        package: com.example.hello
        pluginClass: HelloPlugin
      ios:
        pluginClass: HelloPlugin

environment:
  sdk: ">=2.1.0 <3.0.0"
  # Flutter versions prior to 1.12 did not support the
  # flutter.plugin.platforms map.
  flutter: ">=1.12.0"

当为更多平台添加插件实现时，应相应地更新 platforms map，例如这是支持 Android、iOS、macOS 和 web 的 hello 插件的 map：

When adding plugin implementations for more platforms, the platforms map should be updated accordingly. For example, here’s the map in the pubspec file for the hello plugin, when updated to add support for macOS and web:

flutter:
  plugin:
    platforms:
      android:
        package: com.example.hello
        pluginClass: HelloPlugin
      ios:
        pluginClass: HelloPlugin
      macos:
        pluginClass: HelloPlugin
      web:
        pluginClass: HelloPlugin
        fileName: hello_web.dart

environment:
  sdk: ">=2.1.0 <3.0.0"
  # Flutter versions prior to 1.12 did not support the
  # flutter.plugin.platforms map.
  flutter: ">=1.12.0"

联合平台 package

Federated platform packages

平台 package 有着同样的格式，但会包含 implements 入口，用于指明 package 实现的平台。例如，实现了 hello package 的 Windows 平台的 hello_windows 插件，会在 flutter: 映射下包含以下内容：

A platform package uses the same format, but includes an implements entry indicating which app-facing package it is an implementation for. For example, a hello_windows plugin containing the Windows implementation for hello would have the following flutter: map:

flutter:
  plugin:
    implements: hello
    platforms:
      windows:
        pluginClass: HelloPlugin

认可的实现

Endorsed implementations

提供给 App 项目使用的 package 可以通过在 platform: 映射下声明 default_package，认可一个平台实现插件。如果 hello 插件认可了 hello_windows，它看起来会是这样：

An app facing package can endorse a platform package by adding a dependency on it, and including it as a default_package in the platforms: map. If the hello plugin above endorsed hello_windows, it would look like this:

flutter:
  plugin:
    platforms:
      android:
        package: com.example.hello
        pluginClass: HelloPlugin
      ios:
        pluginClass: HelloPlugin
      windows:
        default_package: hello_windows

dependencies:
  hello_windows: ^1.0.0

注意如上所示，面向 App 项目的 package 可能已经包含了某些平台的实现，同时也有认可的其他平台的实现。

Note that as shown here, an app-facing package can have some platforms implementated within the package, and others in endorsed federated implementations.

第一步：创建 package

Step 1: Create the package

想要创建原生插件 package，请使用带有 --template=plugin 标志的 flutter create 命令。

To create a plugin package, use the --template=plugin flag with flutter create.

从 Flutter 1.20.0 版本，我们开始使用 --platforms= 这个选项，后面参数是用逗号分隔的列表，这个参数代表指定插件支持的平台。可用的平台有：android、ios、web、linux、macos 和 windows。如果没有指定平台，则生成的项目不支持任何平台。

As of Flutter 1.20.0, Use the --platforms= option followed by a comma separated list to specify the platforms that the plugin supports. Available platforms are: android, ios, web, linux, macos, and windows. If no platforms are specified, the resulting project doesn’t support any platforms.

使用 --org 选项，以反向域名表示法来指定你的组织。该值用于生成的 Android 及 iOS 代码。

Use the --org option to specify your organization, using reverse domain name notation. This value is used in various package and bundle identifiers in the generated plugin code.

使用 -a 选项指定 Android 的语言，或使用 -i 选项指定 iOS 的语言。请选择以下 任一项：

Use the -a option to specify the language for android or the -i option to specify the language for ios. Please choose one of the following:

$ flutter create --org com.example --template=plugin --platforms=android,ios -a kotlin hello

$ flutter create --org com.example --template=plugin --platforms=android,ios -a java hello

$ flutter create --org com.example --template=plugin --platforms=android,ios -i objc hello

$ flutter create --org com.example --template=plugin --platforms=android,ios -i swift hello

这将在 hello 目录下创建一个插件项目，其中包含以下内容：

This creates a plugin project in the hello folder with the following specialized content:

lib/hello.dart 文件
Dart 插件 API 实现。

lib/hello.dart
The Dart API for the plugin.

android/src/main/java/com/example/hello/HelloPlugin.kt 文件
Android 平台原生插件 API 实现（使用 Kotlin 编程语言）。

android/src/main/java/com/example/hello/HelloPlugin.kt
The Android platform-specific implementation of the plugin API in Kotlin.

ios/Classes/HelloPlugin.m 文件
iOS 平台原生插件 API 实现（使用 Objective-C 编程语言）。

ios/Classes/HelloPlugin.m
The iOS-platform specific implementation of the plugin API in Objective-C.

example/ 文件
一个依赖于该插件并说明了如何使用它的 Flutter 应用。

example/
A Flutter app that depends on the plugin, and illustrates how to use it.

默认情况下，插件项目中 iOS 代码使用 Swift 编写， Android 代码使用 Kotlin 编写。如果你更喜欢 Objective-C 或 Java，你可以通过 -i 指定 iOS 所使用的语言和/或使用-a 指定 Android 所使用的语言。比如：

By default, the plugin project uses Swift for iOS code and Kotlin for Android code. If you prefer Objective-C or Java, you can specify the iOS language using -i and the Android language using -a. For example:

$ flutter create --template=plugin --platforms=android,ios -i objc hello

$ flutter create --template=plugin --platforms=android,ios -a java hello

第二步：实现 package

Step 2: Implement the package

由于原生插件类型的 package 包含了使用多种编程语言编写的多个平台代码，因此需要一些特定步骤来保证体验的流畅性。

As a plugin package contains code for several platforms written in several programming languages, some specific steps are needed to ensure a smooth experience.

步骤 2a：定义 package API（.dart）

Step 2a: Define the package API (.dart)

原生插件类型 package 的 API 在 Dart 代码中要首先定义好，使用你钟爱的 Flutter 编辑器，打开 hello 主目录，并找到 lib/hello.dart 文件。

The API of the plugin package is defined in Dart code. Open the main hello/ folder in your favorite Flutter editor. Locate the file lib/hello.dart.

步骤 2b：添加 Android 平台代码（.kt/.java）

Step 2b: Add Android platform code (.kt/.java)

我们建议你使用 Android Studio 来编辑 Android 代码。

We recommend you edit the Android code using Android Studio.

接下来进行如下步骤：

Then use the following steps:

启动 Android Studio；
Launch Android Studio.
在 Android Studio 的欢迎菜单 (Welcome to Android Studio) 对话框中选择打开现有的 Android Studio 项目 (Open an existing Android Studio Project)，或在菜单中选择 File > Open，然后选择 hello/example/android/build.gradle 文件；
Select Open an existing Android Studio Project in the Welcome to Android Studio dialog, or select File > Open from the menu, and select the hello/example/android/build.gradle file.
在Gradle Sync 对话框中，选择 OK；
In the Gradle Sync dialog, select OK.
在“Android Gradle Plugin Update”对话框中，选择“Don’t remind me again for this project”。
In the Android Gradle Plugin Update dialog, select Don’t remind me again for this project.

插件中与 Android 系统徐相关的代码在 hello/java/com.example.hello/HelloPlugin 这个文件里。

The Android platform code of your plugin is located in hello/java/com.example.hello/HelloPlugin.

你可以在 Android Studio 中点击运行 ▶ 按钮来运行示例程序。

You can run the example app from Android Studio by pressing the run (▶) button.

步骤 2c：添加 iOS 平台代码（.swift/.h+.m）

Step 2c: Add iOS platform code (.swift/.h+.m)

我们建议你使用 Xcode 来编辑 iOS 代码。

We recommend you edit the iOS code using Xcode.

使用 Xcode 编辑 iOS 平台代码之前，首先确保代码至少被构建过一次（即从 IDE/编辑器执行示例程序，或在终端中执行以下命令： cd hello/example; flutter build ios --no-codesign）。

Before editing the iOS platform code in Xcode, first make sure that the code has been built at least once (in other words, run the example app from your IDE/editor, or in a terminal execute cd hello/example; flutter build ios --no-codesign).

接下来执行下面步骤：

Then use the following steps:

启动 Xcode
Launch Xcode.
选择“File > Open”，然后选择 hello/example/ios/Runner.xcworkspace 文件。
Select File > Open, and select the hello/example/ios/Runner.xcworkspace file.

插件的 iOS 平台代码位于项目导航中的这个位置： Pods/Development Pods/hello/../../example/ios/.symlinks/plugins/hello/ios/Classes。

The iOS platform code for your plugin is located in Pods/Development Pods/hello/../../example/ios/.symlinks/plugins/hello/ios/Classes in the Project Navigator.

你可以点击运行 ▶ 按钮来运行示例程序。

You can run the example app by pressing the run (▶) button.

步骤 2d：关联 API 和平台代码

Step 2d: Connect the API and the platform code

最后，你需要将 Dart 编写的 API 代码与特定平台的实现相互关联。这是通过平台通道完成的。

Finally, you need to connect the API written in Dart code with the platform-specific implementations. This is done using a platform channel, or through the interfaces defined in a platform interface package.

为现有的插件项目加入平台的支持

Add support for platforms in an existing plugin project

要在现有的插件项目中添加对特定平台的支持，请在项目目录运行 flutter create 命令，并加入 --template=plugin。例如，要对现有的插件项目添加 Web 支持，请运行以下命令。

To add support for specific platforms to an existing plugin project, run flutter create with the --template=plugin flag again in the project directory. For example, to add web support in an existing plugin, run:

$ flutter create --template=plugin --platforms=web .

如果这个命令返回了一个关于需要更新 pubspec.yaml 文件的提醒，请按照提示的说明进行操作。

If this command displays a message about updating the pubspec.yaml file, follow the provided instructions.

仅 Dart 的平台实现

Dart-only platform implementations

如先前描述，通常插件会使用第二种语言，实现对应平台的功能。然而，在某些场景下，部分平台可能会完全使用 Dart 进行实现（例如使用 FFI）。若需要仅 Dart 的平台实现，你可以将 pubspec.yaml 里的 pluginClass 替换为 dartPluginClass。下面是 hello_windows 示例替换为仅 Dart 实现的代码：

Usually plugin implementations involve platform channels and a second language, as described above. In some cases, however, some platforms can be implemented entirely in Dart (for example, using FFI). For a Dart-only platform implementation, replace the pluginClass in pubspec.yaml with a dartPluginClass. Here is the hello_windows example above modified for a Dart-only implementation:

flutter:
  plugin:
    implements: hello
    platforms:
      windows:
        dartPluginClass: HelloPluginWindows

在这样的模式下，插件内不包含 Windows 的 C++ 代码，它将继承 hello 插件的 Dart 平台接口，使用包含静态 registerWith() 方法的 HelloPluginWindows 类进行实现。该方法会在启动时调用，用于注册 Dart 实现：

In this version you would have no C++ Windows code, and would instead subclass the hello plugin’s Dart platform interface class with a HelloPluginWindows class that includes a static registerWith() method. This method will be called during startup, and can be used to register the Dart implementation:

class HelloPluginWindows extends HelloPluginPlatform {
  /// Registers this class as the default instance of [HelloPluginPlatform].
  static void registerWith() {
    HelloPluginPlatform.instance = HelloPluginWindows();
  }

从 Flutter 2.5 版本开始，此类插件可以用于 Windows、macOS 和 Linux 插件， Android 和 iOS 在 Flutter 2.8 版本后可用。

This is supported for Windows, macOS, and Linux starting in Flutter 2.5, and for Android and iOS starting in Flutter 2.8.

测试你的插件

Testing your plugin

我们鼓励您使用自动化测试来测试您的插件，以确保代码在修改时候功能保持完整。更多信息，请参见文档支持新的 Android 的 API 中关于测试你的插件这个小节。

We encourage you test your plugin with automated tests, to ensure that functionality does not regress as you make changes to your code. For more information, see Testing your plugin, a section in Supporting the new Android plugins APIs.

添加文档

Adding documentation

建议将下列文档添加到所有 package 中：

It is recommended practice to add the following documentation to all packages:

README.md 文件用来对 package 进行介绍
A README.md file that introduces the package
CHANGELOG.md 文件用来记录每个版本的更改
A CHANGELOG.md file that documents changes in each version
LICENSE 文件用来阐述 package 的许可条款
A LICENSE file containing the terms under which the package is licensed
API 文档包含所有的公共 API（详情参见下文）
API documentation for all public APIs (see below for details)

API 文档

API documentation

当你提交一个 package 时，会自动生成 API 文档并将其提交到 pub.flutter-io.cn/documentation，示例请参见 device_info 文档。

When you publish a package, API documentation is automatically generated and published to pub.dev/documentation. For example, see the docs for device_info.

如果你希望在本地开发环境中生成 API 文档，可以使用以下命令：

If you wish to generate API documentation locally on your development machine, use the following commands:

将当前工作目录切换到 package 所在目录：Change directory to the location of your package:
```
cd ~/dev/mypackage
```
告知文档工具 Flutter SDK 所在位置（请自行更改 Flutter SDK 该在的位置）Tell the documentation tool where the Flutter SDK is located (change the following commands to reflect where you placed it):
```
   export FLUTTER_ROOT=~/dev/flutter  # on macOS or Linux (适用于 macOS 或 Linux 操作系统)

   set FLUTTER_ROOT=~/dev/flutter     # on Windows (适用于 Windows 操作系统)
```

运行 `dartdoc` 工具（已经包含到 Flutter SDK 了）：Run the `dartdoc` tool (included as part of the Flutter SDK), as follows:

   $FLUTTER_ROOT/bin/cache/dart-sdk/bin/dartdoc   # on macOS or Linux (适用于 macOS 或 Linux 操作系统)

   %FLUTTER_ROOT%\bin\cache\dart-sdk\bin\dartdoc  # on Windows (适用于 Windows 操作系统)

关于如何编写 API 文档的建议，请参阅高效 Dart 指南。

For tips on how to write API documentation, see Effective Dart Documentation.

将许可证添加到 LICENSE 文件中

Adding licenses to the LICENSE file

每个 LICENSE 文件中的各个许可证应由 80 个短线字符组成的线段进行分割。

Individual licenses inside each LICENSE file should be separated by 80 hyphens on their own on a line.

如果 LICENSE 文件中包含多个组件许可证，那么每个组件许可证必须以其所在 package 的名称开始，每个 package 名称单独一行显示，并且 package 名称列表与实际许可证内容由空行隔开。（package 名称则需与 pub package 相匹配。比如，一个 package 可能包含多个第三方代码，并且可能需要为每个 package 添加许可证。）

If a LICENSE file contains more than one component license, then each component license must start with the names of the packages to which the component license applies, with each package name on its own line, and the list of package names separated from the actual license text by a blank line. (The packages need not match the names of the pub package. For example, a package might itself contain code from multiple third-party sources, and might need to include a license for each one.)

如下是一些优秀的许可证文件：

The following example shows a well-organized license file:

package_1

<some license text>

--------------------------------------------------------------------------------
package_2

<some license text>

这些也是可以的：

Here is another example of a well-organized license file:

package_1

<some license text>

--------------------------------------------------------------------------------
package_1
package_2

<some license text>

这些是一些不太好的示例：

Here is an example of a poorly-organized license file:

<some license text>

--------------------------------------------------------------------------------
<some license text>

这也是一些不太好的示例：

Another example of a poorly-organized license file:

package_1

<some license text>
--------------------------------------------------------------------------------
<some license text>

提交 package

Publishing your package

一旦完成了 package 的实现，你便可以将其提交到 pub.dev 上，以便其他开发者可以轻松地使用它。

Once you have implemented a package, you can publish it on pub.dev, so that other developers can easily use it.

发布你的 package 之前，确保检查了这几个文件：pubspec.yaml、README.md 和 CHANGELOG.md，确保它们完整且争取，另外，为了提高 package 的可用性，可以考虑加入如下的内容：

Prior to publishing, make sure to review the pubspec.yaml, README.md, and CHANGELOG.md files to make sure their content is complete and correct. Also, to improve the quality and usability of your package (and to make it more likely to achieve the status of a Flutter Favorite), consider including the following items:

代码的示例用法
Diverse code usage
屏幕截图，GIF 动画或者视频
Screenshots, animated gifs, or videos
代码库的正确指向链接
A link to the corresponding code repository

接下来，运行 dry-run 命令以检验是否所有内容都通过了分析：

Next, run the publish command in dry-run mode to see if everything passes analysis:

$ flutter pub publish --dry-run

最后一步是发布，请注意：发布是永久性的，运行以下提交命令：

The next step is publishing to pub.dev, but be sure that you are ready because publishing is forever:

$ flutter pub publish

设置了中国镜像的开发者们请注意：目前所存在的镜像都不能（也不应该）进行 package 的上传。如果你设置了镜像，执行上述发布代码可能会造成发布失败。网络设定好后，无需取消中文镜像，执行下述代码可直接上传：

$ flutter pub publish --server=https://pub.dartlang.org

有关提交的详细信息，请查阅关于 Pub 站点的提交文档。

For more details on publishing, see the publishing docs on dart.dev.

Package 依赖处理

Handling package interdependencies

如果你正在开发的 hello 依赖于另外一个 package 所公开的 Dart API，你需要将该 package 添加到文件 pubspec.yaml 的 dependencies 段中。以下代码使得插件 url_launcher 的 Dart API 在 hello 中可用：

If you are developing a package hello that depends on the Dart API exposed by another package, you need to add that package to the dependencies section of your pubspec.yaml file. The code below makes the Dart API of the url_launcher plugin available to hello:

dependencies:
  url_launcher: ^5.0.0

现在你可以在 hello 的 Dart 代码中使用 import 'package:url_launcher/url_launcher.dart' 和 launch(someUrl)。

You can now import 'package:url_launcher/url_launcher.dart' and launch(someUrl) in the Dart code of hello.

这与你在 Flutter 应用或其他任何 Dart 项目中引入 package 的方式没什么区别。

This is no different from how you include packages in Flutter apps or any other Dart project.

但碰巧 hello 是一个 原生插件 package，其特定的平台代码如果需要访问 url_launcher 所公开的平台特定 API，那么还需要为特定平台的构建文件添加适当的依赖说明，如下所示：

But if hello happens to be a plugin package whose platform-specific code needs access to the platform-specific APIs exposed by url_launcher, you also need to add suitable dependency declarations to your platform-specific build files, as shown below.

Android

在 hello/android/build.gradle 文件中为 url_launcher 插件设定依赖关系。

The following example sets a dependency for url_launcher in hello/android/build.gradle:

android {
    // lines skipped
    dependencies {
        compileOnly rootProject.findProject(":url_launcher")
    }
}

现在你可以在 hello/android/src 目录下的源代码文件中使用 import io.flutter.plugins.urllauncher.UrlLauncherPlugin 并访问文件 UrlLauncherPlugin。

You can now import io.flutter.plugins.urllauncher.UrlLauncherPlugin and access the UrlLauncherPlugin class in the source code at hello/android/src.

如果希望了解更多有关 build.gradle 文件更多的信息，请参阅 Gradle 文档了解构建脚本。

For more information on build.gradle files, see the Gradle Documentation on build scripts.

iOS

在 hello/ios/hello.podspec 文件中为 url_launcher 插件设定依赖关系。

The following example sets a dependency for url_launcher in hello/ios/hello.podspec:

Pod::Spec.new do |s|
  # lines skipped
  s.dependency 'url_launcher'

现在你可以在 hello/ios/Classes 目录下的源代码文件中使用 #import "UrlLauncherPlugin.h" 并访问 UrlLauncherPlugin 这个类了。

You can now #import "UrlLauncherPlugin.h" and access the UrlLauncherPlugin class in the source code at hello/ios/Classes.

如果希望了解更多有关 .podspec 文件更多的信息，请参阅 CocoaPods 文档了解。

For additional details on .podspec files, see the CocoaPods Documentation on them.

Web

与其他的 Dart package 一样，所有的 Web 依赖都由文件 pubspec.yaml 来处理。

All web dependencies are handled by the pubspec.yaml file like any other Dart package.

Flutter Favorite 项目

指标
Metrics
Flutter 生态系统委员会
Flutter Ecosystem Committee
Flutter Favorite 使用指南
Flutter Favorite usage guidelines
下一步工作
What’s next
Flutter Favorites

The Flutter Favorite program logo

Flutter Favorite 项目是为了在你构建应用时，能够向你提供你应该优先考虑的 package 和插件。这并不意味着它能够在你的特定情况下保证你的产品质量和适用性— 你应该始终针对你的项目情况对 packages 和插件进行自我评估。

The aim of the Flutter Favorite program is to identify packages and plugins that you should first consider when building your app. This is not a guarantee of quality or suitability to your particular situation—you should always perform your own evaluation of packages and plugins for your project.

你可以在 pub.dev 上看到完整的 Flutter Favorite packages 列表。

You can see the complete list of Flutter Favorite packages on pub.dev.

指标

Metrics

Flutter Favorite packages 通过以下指标来确认是否达到高质量标准：

Flutter Favorite packages have passed high quality standards using the following metrics:

Package 的整体分数
Overall package score
宽松许可证, 包括但不限于 Apache、Artistic、BSD、CC BY、MIT、MS-PL 和 W3C
Permissive license, including (but not limited to) Apache, Artistic, BSD, CC BY, MIT, MS-PL and W3C
GitHub 版本标签与从 pub.dev 获取的当前版本匹配，以便你可以准确地看到 packages 的源码
GitHub version tag matches the current version from pub.dev, so you can see exactly what source is in the package
特性完整 ——并且没有被标记为不完整（例如带着「beta」或「under construction」标签)
Feature completeness—and not marked as incomplete (for example, with labels like “beta” or “under construction”)
成为已验证发布者
Verified publisher
当其涉及到概述、文档、样本/示例代码和 API 质量时，具备一般 可用性
General usability when it comes to the overview, docs, sample/example code, and API quality
在 CPU 和内存占用方面，具有优异的 运行时行为
Good runtime behavior in terms of CPU and memory usage
高质量 依赖项
High quality dependencies

Flutter 生态系统委员会

Flutter Ecosystem Committee

Flutter 生态系统委员会（FEC）由 Flutter 团队成员和社区成员组成并贯穿其生态系统。他们的工作之一就是确定一个 package 是否满足成为 Flutter Favorite 的质量要求。

The Flutter Ecosystem Committee (FEC) is comprised of Flutter team members and Flutter community members spread across its ecosystem. One of their jobs is to decide when a package has met the quality bar to become a Flutter Favorite.

当前的委员会成员（按姓氏字母排序）如下所示：

The current committee members (ordered alphabetically by last name) are as follows:

Pooja Bhaumik
Hillel Coren
Thea Flowers
Simon Lightfoot
Lara Martín
Chris Sells (committee chair)
Michael Thomsen
Diego Velasquez
Kyle Wang

如果你想提名一个 package 或插件成为潜在的 Flutter Favorite，亦或是想提请其他需要引起注意的问题至委员会，请发送邮件至委员会主席。

If you’d like to nominate a package or plugin as a potential future Flutter Favorite, or would like to bring any other issues to the attention of the committee, send the committee chair an email.

Flutter Favorite 使用指南

Flutter Favorite usage guidelines

Flutter Favorite packages 会由 Flutter 团队在 pub.dev 上标注。如果你拥有一个 package 被标注未 Flutter Favorite，那么你必须遵守以下准则：

Flutter Favorite packages are labeled as such on pub.dev by the Flutter team. If you own a package that has been designated as a Flutter Favorite, you must adhere to the following guidelines:

Flutter Favorite package 的作者可以将 Flutter Favorite 徽标放置在 package 的 GitHub README 中， pub.dev 上 package 主页的 Overview 处，以及社交媒体上与该 package 相关的帖子中。
Flutter Favorite package authors may place the Flutter Favorite logo in the package’s GitHub README, on the package’s pub.dev Overview tab, and on social media as related to posts about that package.
我们鼓励你在社交媒体上使用 #FlutterFavorite 标签。
We encourage you to use the #FlutterFavorite hashtag in social media.
当使用 Flutter Favorite 的标志时，作者必须提供跳转至此 Flutter Favorite 着陆页的链接，以说明该徽标的来龙去脉。
When using the Flutter Favorite logo, the author must link to (this) Flutter Favorite landing page, to provide context for the designation.
假定一个 Flutter Favorite package 失去了它的 Flutter Favorite 标记，作者将收到通知。届时，作者必须立即删除所有受影响的 packages 所使用「Flutter Favorite」和「Flutter Favorite 徽标」。
If a Flutter Favorite package loses its Flutter Favorite status, the author will be notified, at which point the author must immediately remove all uses of “Flutter Favorite” and the Flutter Favorite logo from the affected package.
不得以任何方式改变、歪曲或修改 Flutter Favorite 的徽标，包括通过颜色变换或未经批准的视觉元素来展示该徽标。
Don’t alter, distort, or modify the Flutter Favorite logo in any way, including displaying the logo with color variations or unapproved visual elements.
不得以误导的方式展示 Flutter Favorite 的徽标，即以误导、不平等、诽谤、侵权、中伤、贬低、淫秽或其他令谷歌反感的方式展示来 Flutter Favorite 徽标。
Don’t display the Flutter Favorite logo in a manner that is misleading, unfair, defamatory, infringing, libelous, disparaging, obscene, or otherwise objectionable to Google.

下一步工作

What’s next

随着生态系统的不断发展，您应该期待 Flutter Favorite packages 名单会不断壮大和更新委员会将持续与 packages 作者合作以提高质量，并思考让生态系统的其他领域，如工具、咨询公司和高产的 Flutter 贡献者，也可以从 Flutter Favorite 计划中获益。

You should expect the list of Flutter Favorite packages to grow and change as the ecosystem continues to thrive. The committee will continue working with package authors to increase quality, as well as consider other areas of the ecosystem that could benefit from the Flutter Favorite program, such as tools, consulting firms, and prolific Flutter contributors.

随着 Flutter 生态系统的发展。我们将着眼于扩大指标设置，其中可能包括以下内容。

As the Flutter ecosystem grows, we’ll be looking at expanding the set of metrics, which might include the following:

使用全新的 pubspec.yaml 格式来明确指出其支持哪些平台。
Use of the new pubspec.yaml format that clearly indicates which platforms are supported.
支持 Flutter 的最新稳定版本。
Support for the latest stable version of Flutter.
对 AndroidX 的支持。
Support for AndroidX.
支持多种平台，如 Web、macOS、Windows 和 Linux 等。
Support for multiple platforms, such as web, macOS, Windows, Linux, etc.
集成以及单元测试覆盖。
Integration as well as unit test coverage.

Flutter Favorites

你可以在 pub.dev 上看到完整的 Flutter Favorite packages 列表。

You can see the complete list of Flutter Favorite packages on pub.dev.

后台进程

当你的应用被切换到后台时，是否仍希望它在后台可以执行一些业务逻辑？在 Flutter 里，你可以在应用被切换到后台时执行一些代码逻辑。

Have you ever wanted to execute Dart code in the background—even if your app wasn’t the currently active app? Perhaps you wanted to implement a process that watches the time, or that catches camera movement. In Flutter, you can execute Dart code in the background.

这个功能的机制主要是设置一个 isolate。isolate 是 Dart 中的多线程模型，不过其与传统线程的不同之处在于它不与主进程共享内存。你可以使用回调和回调调度器来设置 isolate，从而使应用被切换进后台时仍能执行一些业务。

The mechanism for this feature involves setting up an isolate. Isolates are Dart’s model for multithreading, though an isolate differs from a conventional thread in that it doesn’t share memory with the main program. You’ll set up your isolate for background execution using callbacks and a callback dispatcher.

有关在后台进程中使用 Dart 代码的 geofencing 案例，你可以查阅发布在 Flutter on Medium 上的一篇文章： Executing Dart in the Background with Flutter Plugins and Geofencing。在这篇文章的最后，你可以找到示例代码的链接，以及相关的 Dart、iOS 和 Android 文档。

For more information and a geofencing example that uses background execution of Dart code, see the Medium article by Ben Konyi, Executing Dart in the Background with Flutter Plugins and Geofencing. At the end of this article, you’ll find links to example code, and relevant documentation for Dart, iOS, and Android.

支持新的 Android 的 API

升级步骤
Upgrade steps
测试您的插件
Testing your plugin
基础插件
Basic plugin
UI/Activity 插件
UI/Activity plugin

如果您并非亲自开发或维护一个 Flutter 的 Android 插件，您可以跳过本页面。

If you don’t write or maintain an Android Flutter plugin, you can skip this page.

自 1.12 版本发布后， Android 平台已可以使用新的 Android 插件 API 。基于 PluginRegistry.Registrar 的 API 不会立刻废弃，但我们鼓励您向基于 FlutterPlugin 的 API 进行迁移。

As of the 1.12 release, new plugin APIs are available for the Android platform. The old APIs based on PluginRegistry.Registrar won’t be immediately deprecated, but we encourage you to migrate to the new APIs based on FlutterPlugin.

相较旧的 API 而言，新版 API 的优点是为生命周期的相关组件提供了更简洁清晰的访问方式。例如，在使用旧的 PluginRegistry.Registrar.activity() 时，如果 Flutter 尚未附加到任何 activites，可能会返回 null 。

The new API has the advantage of providing a cleaner set of accessors for lifecycle dependent components compared to the old APIs. For instance PluginRegistry.Registrar.activity() could return null if Flutter isn’t attached to any activities.

换句话说，在使用旧的 API 进行 Flutter 嵌入 Android 应用时，可能会产生意外的行为。 Flutter 开发团队提供的大部分 Flutter 插件已经完成了迁移。（了解如何成为认证的发布者）作为参考， battery package 已经迁移到新版 API 。

In other words, plugins using the old API may produce undefined behaviors when embedding Flutter into an Android app. Most of the Flutter plugins provided by the flutter.dev team have been migrated already. (Learn how to become a verified publisher on pub.dev!) For an example of a plugin that uses the new APIs, see the battery package.

升级步骤

Upgrade steps

以下的步骤简要说明了如何支持新版 API ：

The following instructions outline the steps for supporting the new API:

在插件的主类文件中 (*Plugin.java) 实现 FlutterPlugin 接口。对于稍微复杂的插件，您可以将 FlutterPlugin 与 MethodCallHandler 拆分到不同的类中。如需更多关于如何使用新版 API 获取资源的内容，请参考下一节基础插件。

同时需要注意的是，插件仍需保留静态的 registerWith() 方法，从而适配不兼容 v2 版本嵌入的应用。 (查看 Upgrading pre 1.12 Android projects 获取更多信息)

此外，所有不可覆盖的公开成员都应该使用文档标注。在嵌入开发的场景下，这些可见内容通常需要包含文档。
Update the main plugin class (*Plugin.java) to implement the FlutterPlugin interface. For more complex plugins, you can separate the FlutterPlugin and MethodCallHandler into two classes. See the next section, Basic plugin, for more details on accessing app resources with the latest version (v2) of embedding.

Also, note that the plugin should still contain the static registerWith() method to remain compatible with apps that don’t use the v2 Android embedding. (See Upgrading pre 1.12 Android projects for details.) The easiest thing to do (if possible) is move the logic from registerWith() into a private method that both registerWith() and onAttachedToEngine() can call. Either registerWith() or onAttachedToEngine() will be called, not both.

In addition, you should document all non-overridden public members within the plugin. In an add-to-app scenario, these classes are accessible to a developer and require documentation.
（可选）如果您的插件需要 Activity 的引用，请同时实现 ActivityAware 接口。
(Optional) If your plugin needs an Activity reference, also implement the ActivityAware interface.
（可选）如果您的插件需要随时保持一个后台 Service ，请实现 ServiceAware 接口。
(Optional) If your plugin is expected to be held in a background Service at any point in time, implement the ServiceAware interface.
使用 FlutterActivity 将示例应用中的 MainActivity.java 迁移到 v2 版本嵌入。更多信息请查看 Upgrading pre 1.12 Android projects 。如果您的插件类尚不存在，则必须添加一个公有构造函数。例如：
Update the example app’s MainActivity.java to use the v2 embedding FlutterActivity. For details, see Upgrading pre 1.12 Android projects. You may have to make a public constructor for your plugin class if one didn’t exist already. For example:
```
 package io.flutter.plugins.firebasecoreexample;

 import io.flutter.embedding.android.FlutterActivity;
 import io.flutter.embedding.engine.FlutterEngine;
 import io.flutter.plugins.firebase.core.FirebaseCorePlugin;

 public class MainActivity extends FlutterActivity {
   // You can keep this empty class or remove it. Plugins on the new embedding
   // now automatically registers plugins.
 }
```

（可选）如果您移除了 MainActivity.java，请更新 <plugin_name>/example/android/app/src/main/AndroidManifest.xml 以使用 io.flutter.embedding.android.FlutterActivity。例如：

(Optional) If you removed MainActivity.java, update the <plugin_name>/example/android/app/src/main/AndroidManifest.xml to use io.flutter.embedding.android.FlutterActivity. For example:

  <activity android:name="io.flutter.embedding.android.FlutterActivity"
         android:theme="@style/LaunchTheme"
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale"
         android:hardwareAccelerated="true"
         android:windowSoftInputMode="adjustResize">
         <meta-data
             android:name="io.flutter.app.android.SplashScreenUntilFirstFrame"
             android:value="true" />
         <intent-filter>
             <action android:name="android.intent.action.MAIN"/>
             <category android:name="android.intent.category.LAUNCHER"/>
         </intent-filter>
     </activity>

（可选）在 MainActivity.java 同级目录下创建一个 EmbeddingV1Activity.java 文件，使用 v1 版本嵌入以持续测试您的项目对 v1 版本嵌入的兼容性。例如：

(Optional) Create an EmbeddingV1Activity.java file] that uses the v1 embedding for the example project in the same folder as MainActivity to keep testing the v1 embedding’s compatibility with your plugin. Note that you have to manually register all the plugins instead of using GeneratedPluginRegistrant. For example:

 package io.flutter.plugins.batteryexample;

 import android.os.Bundle;
 import dev.flutter.plugins.e2e.E2EPlugin;
 import io.flutter.app.FlutterActivity;
 import io.flutter.plugins.battery.BatteryPlugin;

 public class EmbeddingV1Activity extends FlutterActivity {
   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     BatteryPlugin.registerWith(registrarFor("io.flutter.plugins.battery.BatteryPlugin"));
     E2EPlugin.registerWith(registrarFor("dev.flutter.plugins.e2e.E2EPlugin"));
   }
 }

将 <meta-data android:name="flutterEmbedding" android:value="2"/> 添加至 <plugin_name>/example/android/app/src/main/AndroidManifest.xml 。这会让示例应用使用 v2 版本的嵌入。
Add <meta-data android:name="flutterEmbedding" android:value="2"/> to the <plugin_name>/example/android/app/src/main/AndroidManifest.xml. This sets the example app to use the v2 embedding.
（可选）如果上步您创建了 EmbeddingV1Activity ，将 EmbeddingV1Activity 添加至 <plugin_name>/example/android/app/src/main/AndroidManifest.xml 文件。例如：
(Optional) If you created an EmbeddingV1Activity in the previous step, add the EmbeddingV1Activity to the <plugin_name>/example/android/app/src/main/AndroidManifest.xml file. For example:
```
 <activity
 android:name=".EmbeddingV1Activity"
 android:theme="@style/LaunchTheme"
 android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale"
 android:hardwareAccelerated="true"
 android:windowSoftInputMode="adjustResize">
 </activity>
```

测试您的插件

Testing your plugin

剩下的步骤让您可以测试您的插件，我们鼓励您这样做，但这并不是必需的。

The remaining steps address testing your plugin, which we encourage, but aren’t required.

替换 <plugin_name>/example/android/app/build.gradle 文件中 android.support.test 的引用为 androidx.test ：

Update <plugin_name>/example/android/app/build.gradle to replace references to android.support.test with androidx.test:

 defaultConfig {
   ...
   testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
   ...
 }

 dependencies {
 ...
 androidTestImplementation 'androidx.test:runner:1.2.0'
 androidTestImplementation 'androidx.test:rules:1.2.0'
 androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0'
 ...
 }

在 <plugin_name>/example/android/app/src/androidTest/java/<plugin_path>/ 路径下添加针对 MainActivity 和 EmbeddingV1Activity 的测试文件，并且您需要创建该目录。例如：

Add tests files for MainActivity and EmbeddingV1Activity in <plugin_name>/example/android/app/src/androidTest/java/<plugin_path>/. You will need to create these directories. For example:

 package io.flutter.plugins.firebase.core;

 import androidx.test.rule.ActivityTestRule;
 import dev.flutter.plugins.e2e.FlutterRunner;
 import io.flutter.plugins.firebasecoreexample.MainActivity;
 import org.junit.Rule;
 import org.junit.runner.RunWith;

 @RunWith(FlutterRunner.class)
 public class MainActivityTest {
   // Replace `MainActivity` with `io.flutter.embedding.android.FlutterActivity` if you removed `MainActivity`.
   @Rule public ActivityTestRule<MainActivity> rule = new ActivityTestRule<>(MainActivity.class);
 }

 package io.flutter.plugins.firebase.core;

 import androidx.test.rule.ActivityTestRule;
 import dev.flutter.plugins.e2e.FlutterRunner;
 import io.flutter.plugins.firebasecoreexample.EmbeddingV1Activity;
 import org.junit.Rule;
 import org.junit.runner.RunWith;

 @RunWith(FlutterRunner.class)
 public class EmbeddingV1ActivityTest {
   @Rule
   public ActivityTestRule<EmbeddingV1Activity> rule =
       new ActivityTestRule<>(EmbeddingV1Activity.class);
 }

在 <plugin_name>/pubspec.yaml 和 <plugin_name>/example/pubspec.yaml 中的 dev_dependencies 下添加 e2e 和 flutter_driver。
Add e2e and flutter_driver dev_dependencies to <plugin_name>/pubspec.yaml and <plugin_name>/example/pubspec.yaml.
```
 e2e: ^0.2.1
 flutter_driver:
 sdk: flutter
```
更新 <plugin_name>/pubspec.yaml 中 Flutter 版本的最低限制。所有已迁移的插件都将会设置最低版本为我们保证支持的最低版本 1.12.13+hotfix.6。例如：
Update minimum Flutter version of environment in <plugin_name>/pubspec.yaml. All plugins moving forward will set the minimum version to 1.12.13+hotfix.6 which is the minimum version for which we can guarantee support. For example:
```
 environment:
 sdk: ">=2.0.0-dev.28.0 <3.0.0"
 flutter: ">=1.12.13+hotfix.6"
```
在 <plugin_name>/test/<plugin_name>_e2e.dart 中创建一个简单的测试。为了测试添加了 v2 版本嵌入支持的 PR，我们将尝试测试一些插件的基础功能。这是一个确保插件正确注册到新的嵌入器的烟雾测试。例如：
Create a simple test in <plugin_name>/test/<plugin_name>_e2e.dart. For the purpose of testing the PR that adds the v2 embedding support, we’re trying to test some very basic functionality of the plugin. This is a smoke test to ensure that the plugin properly registers with the new embedder. For example:
```
import 'package:flutter_test/flutter_test.dart';
 import 'package:battery/battery.dart';
 import 'package:e2e/e2e.dart';

 void main() {
 E2EWidgetsFlutterBinding.ensureInitialized();

 testWidgets('Can get battery level', (WidgetTester tester) async {
 final Battery battery = Battery();
 final int batteryLevel = await battery.batteryLevel;
 expect(batteryLevel, isNotNull);
 });
 }
```

本地运行 e2e 测试。在终端中执行以下内容：

Test run the e2e tests locally. In a terminal, do the following:

 cd <plugin_name>/example
 flutter build apk
 cd android
 ./gradlew app:connectedAndroidTest -Ptarget=`pwd`/../../test/<plugin_name>_e2e.dart

基础插件

Basic plugin

要开始开发一个新的 Flutter Android 插件，请从 FlutterPlugin 的实现开始。

To get started with a Flutter Android plugin in code, start by implementing FlutterPlugin.

public class MyPlugin implements FlutterPlugin {
  @Override
  public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
    // TODO: your plugin is now attached to a Flutter experience.
  }

  @Override
  public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {
    // TODO: your plugin is no longer attached to a Flutter experience.
  }
}

如上述代码所示，您的插件在任意时刻都可能与 Flutter 的体验有关或无关。您需要特别注意，在 onAttachedToEngine() 进行初始化，并且在 onDetachedFromEngine() 中进行清理插件的各种引用。

As shown above, your plugin may or may not be associated with a given Flutter experience at any given moment in time. You should take care to initialize your plugin’s behavior in onAttachedToEngine(), and then cleanup your plugin’s references in onDetachedFromEngine().

FlutterPluginBinding 为您的插件提供了几个重要的引用：

The FlutterPluginBinding provides your plugin with a few important references:

binding.getFlutterEngine()
返回插件附加到的 FlutterEngine ，提供了诸如 DartExecutor 、 FlutterRenderer 等内容的获取。

binding.getFlutterEngine()
Returns the FlutterEngine that your plugin is attached to, providing access to components like the DartExecutor, FlutterRenderer, and more.

binding.getApplicationContext()
返回当前运行的安卓应用的 Application Context 。

binding.getApplicationContext()
Returns the Android application’s Context for the running app.

UI/Activity 插件

UI/Activity plugin

如果您的插件需要与 UI 进行交互，例如请求权限或更改 Android UI ，那么您就需要一些附加步骤来构建您的插件。您必须实现 ActivityAware 接口。

If your plugin needs to interact with the UI, such as requesting permissions, or altering Android UI chrome, then you need to take additional steps to define your plugin. You must implement the ActivityAware interface.

public class MyPlugin implements FlutterPlugin, ActivityAware {
  //...normal plugin behavior is hidden...

  @Override
  public void onAttachedToActivity(ActivityPluginBinding activityPluginBinding) {
    // TODO: your plugin is now attached to an Activity
  }

  @Override
  public void onDetachedFromActivityForConfigChanges() {
    // TODO: the Activity your plugin was attached to was
    // destroyed to change configuration.
    // This call will be followed by onReattachedToActivityForConfigChanges().
  }

  @Override
  public void onReattachedToActivityForConfigChanges(ActivityPluginBinding activityPluginBinding) {
    // TODO: your plugin is now attached to a new Activity
    // after a configuration change.
  }

  @Override
  public void onDetachedFromActivity() {
    // TODO: your plugin is no longer associated with an Activity.
    // Clean up references.
  }
}

若需要与 Activity 交互，您已经实现 ActivityAware 的插件需要在 4 个不同的阶段实现不同的行为。首先，确保您的插件已经附加至 Activity 。您可以通过提供的 ActivityPluginBinding 获取到 Activity 及一些回调。

To interact with an Activity, your ActivityAware plugin must implement appropriate behavior at 4 stages. First, your plugin is attached to an Activity. You can access that Activity and a number of its callbacks through the provided ActivityPluginBinding.

由于 Activity 有可能在配置变化时被销毁，您必须在 onDetachedFromActivityForConfigChanges() 方法中清理所有与 Activity 有关的引用，接着在 onReattachedToActivityForConfigChanges() 中重新建立它们。

Since Activitys can be destroyed during configuration changes, you must cleanup any references to the given Activity in onDetachedFromActivityForConfigChanges(), and then re-establish those references in onReattachedToActivityForConfigChanges().

最后，在 onDetachedFromActivity() 中清理所有与 Activity 有关的引用并返回与 UI 无关的配置。

Finally, in onDetachedFromActivity() your plugin should clean up all references related to Activity behavior and return to a non-UI configuration.

将 Flutter 集成到现有应用

集成到现有应用
Add-to-app
已支持的特性
Supported features
- 集成到 Android 应用
  Add to Android applications
- 集成到 iOS 应用
  Add to iOS applications
开始
Get started
API 用法
API usage

集成到现有应用

Add-to-app

有时候，用 Flutter 一次性重写整个已有的应用是不切实际的。对于这些情况，Flutter 可以作为一个库或模块，集成进现有的应用当中。模块引入到您的 Android 或 iOS 应用（当前支持的平台）中，以使用 Flutter 来渲染一部分的 UI，或者仅运行多平台共享的 Dart 代码逻辑。

It’s sometimes not practical to rewrite your entire application in Flutter all at once. For those situations, Flutter can be integrated into your existing application piecemeal, as a library or module. That module can then be imported into your Android or iOS (currently supported platforms) app to render a part of your app’s UI in Flutter. Or, just to run shared Dart logic.

仅需几步，你就可以将高效而富有表现力的 Flutter 引入您的应用。

In a few steps, you can bring the productivity and the expressiveness of Flutter into your own app.

在 Flutter v1.12 中，添加到现有应用的基本场景已被支持，每个应用在同一时间可以集成一个全屏幕的 Flutter 实例。目前仍有以下限制：

As of Flutter v1.12, add-to-app is supported for the basic scenario of integrating one full-screen Flutter instance at a time per app. It currently has the following limitations:

目前尚未支持将多个 Flutter 库打包到同一个应用中；
Packing multiple Flutter libraries into an application isn’t supported.
在 Android 平台，使用了添加到现有应用 (add-to-app) 的插件需要迁移到基于 FlutterPlugin 的 Android 插件 API。
Plugins used in add-to-app on Android should migrate to the new Android plugin APIs, based on FlutterPlugin.
一些不支持 FlutterPlugin 的插件可能会有不可预知的行为，比如产生错误的预判，认为 Flutter Activity 一直处于活跃状态。
Plugins that don’t support FlutterPlugin might have unexpected behaviors if they make assumptions that are untenable in add-to-app (such as assuming that a Flutter Activity is always present).
从 1.17 开始，Flutter 模块仅支持 Android 平台中的 AndroidX 应用。
As of v1.17, the Flutter module only supports AndroidX applications on Android.

自 Flutter 1.26 版本开始，add-to-app 开始实验性的支持将多个 Flutter 引擎 (engine)、页面 (screen) 或视图 (view) 添加到你的应用中。适用于混合栈应用在导航到原生页面和 Flutter 页面的情况，也适用于一个页面有原生视图和 Flutter 视图的情况等混合栈应用。多个 Flutter 实例会帮助每个实例保持独立的应用和 UI 状态，同时使用最少的内存资源。请多详细内容，请参考文档：多个 Flutter 实例。

As of Flutter v1.26, add-to-app experimentally supports adding multiple instances of Flutter engines, screens, or views into your app. This can help integration scenarios such as a hybrid navigation stack with mixed native and Flutter screens, or a page with multiple partial-screen Flutter views. Having multiple Flutter instances allows each instance to maintain independent application and UI state while using minimal memory resources. See more in the multiple Flutters page.

已支持的特性

Supported features

集成到 Android 应用

Add to Android applications

在 Gradle 脚本中添加一个自动构建并引入 Flutter 模块的 Flutter SDK 钩子。
Auto-build and import the Flutter module by adding a Flutter SDK hook to your Gradle script.
将 Flutter 模块构建为通用的 Android Archive (AAR) 以便集成到您自己的构建系统中，并提高 Jetifier 与 AndroidX 的互操作性；
Build your Flutter module into a generic Android Archive (AAR) for integration into your own build system and for better Jetifier interoperability with AndroidX.
FlutterEngine API 用于启动并持续地为挂载 FlutterActivity 或 FlutterFragment 提供独立的 Flutter 环境；
FlutterEngine API for starting and persisting your Flutter environment independently of attaching a FlutterActivity/FlutterFragment etc.
Android Studio 的 Android 与 Flutter 同时编辑，以及 Flutter module 创建与导入向导；
Android Studio Android/Flutter co-editing and module creation/import wizard.
支持了 Java 和 Kotlin 为宿主的应用程序；
Java and Kotlin host apps are supported.
Flutter 模块可以通过使用 Flutter plugins 与平台进行交互。 Android 平台的 plugin 应该迁移至 V2 plugin API 以确保最佳的兼容性。在 Flutter v1.12，大多数 Flutter 团队维护的 plugin，以及 FlutterFire 都已完成迁移；
Flutter modules can use Flutter plugins to interact with the platform. Android plugins should be migrated to the V2 plugins APIs for best add-to-app correctness. As of Flutter v1.12, most of the plugins maintained by the Flutter team as well as FlutterFire have been migrated.
支持通过从 IDE 或命令行中使用 flutter attach 来实现 Flutter 调试与有状态的热重载。
Support for Flutter debugging and stateful hot reload by using flutter attach from IDEs or the command line to connect to an app that contains Flutter.

集成到 iOS 应用

Add to iOS applications

在 Xcode 的 Build Phase 以及 CocoaPods 中，添加一个自动构建并引入 Flutter 模块的 Flutter SDK 钩子。
Auto-build and import the Flutter module by adding a Flutter SDK hook to your CocoaPods and to your Xcode build phase.
将 Flutter 模块构建为通用的 iOS Framework 以便集成到您自己的构建系统中；
Build your Flutter module into a generic iOS Framework for integration into your own build system.
FlutterEngine API 用于启动并持续地为挂载 FlutterViewController 以提供独立的 Flutter 环境；
FlutterEngine API for starting and persisting your Flutter environment independently of attaching a FlutterViewController.
支持了 Objective-C 和 Swift 为宿主的应用程序；
Objective-C and Swift host apps supported.
Flutter 模块可以通过使用 Flutter plugins 与平台进行交互；
Flutter modules can use Flutter plugins to interact with the platform.
支持通过从 IDE 或命令行中使用 flutter attach 来实现 Flutter 调试与有状态的热重载。
Support for Flutter debugging and stateful hot reload by using flutter attach from IDEs or the command line to connect to an app that contains Flutter.

查看 add-to-app GitHub 示例仓库中在 iOS 和 Android 平台上引入 Flutter module 的示例项目。

See our add-to-app GitHub Samples repository for sample projects in Android and iOS that import a Flutter module for UI.

开始

Get started

第一步，查看以下工程集成指南

To get started, see our project integration guide for Android and iOS:

Android

iOS

API 用法

API usage

将 Flutter 集成进您的工程后，可以查看以下 API 使用指南

After Flutter is integrated into your project, see our API usage guides at the following links:

Android

iOS

将 Flutter module 集成到 Android 项目

使用 Android Studio
Using Android Studio
手动集成
Manual integration

Flutter 可以作为 Gradle 子项目源码或者 AAR 嵌入到现有的 Android 应用程序中。

Flutter can be embedded into your existing Android application piecemeal, as a source code Gradle subproject or as AARs.

开发者可以使用带有 Flutter 插件的 Android Studio 或手动完成整个集成流程。

The integration flow can be done using the Android Studio IDE with the Flutter plugin or manually.

请注意

你目前现有的 Android 项目可能支持 mips 或 x86 之类的架构，然而，Flutter 当前仅支持为 x86_64，armeabi-v7a 和 arm64-v8a 构建预编（AOT）的库。

Your existing Android app may support architectures such as mips or x86. Flutter currently only supports building ahead-of-time (AOT) compiled libraries for x86_64, armeabi-v7a and arm64-v8a.

可以考虑使用 abiFilters 这个 Android Gradle 插件 API 来指定 APK 中支持的架构，从而避免 libflutter.so 无法生成而导致应用运行时崩溃，具体操作如下：

Consider using the abiFilters Android Gradle Plugin API to limit the supported architectures in your APK. Doing this avoids a missing libflutter.so runtime crash, for example:

android {
  //...
  defaultConfig {
    ndk {
      // Filter for architectures supported by Flutter.
      abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86_64'
    }
  }
}

Flutter 引擎支持 x86 和 x86_64 的版本，在模拟器以 debug 即时编译 (JIT) 模式运行时， Flutter 模块仍可以正常运行。

The Flutter engine has an x86 and x86_64 version. When using an emulator in debug Just-In-Time (JIT) mode, the Flutter module still runs correctly.

使用 Android Studio

Using Android Studio

直接使用 Android Studio 是在现有应用中自动集成 Flutter 模块比较便捷的方法。在 Android Studio 中，你可以在一个项目中同时编写 Android 代码和 Flutter 代码，还可以继续使用各种常用的 IntelliJ Flutter 插件功能，例如 Dart 代码自动补全、热重载和 widget 检查器等。

The Android Studio IDE is a convenient way of integrating your Flutter module automatically. With Android Studio, you can co-edit both your Android code and your Flutter code in the same project. You can also continue to use your normal IntelliJ Flutter plugin functionalities such as Dart code completion, hot reload, and widget inspector.

只有在 Android Studio 3.6 及以上的版本，配合 42 以上版本的 IntelliJ Flutter 插件才能直接通过 Android Studio 执行集成流程，并且，Android Studio 目前仅支持以 Gradle 子项目源码的方式集成，而不能以 AAR 方式集成。有关这两种方式的区别及更多详细信息，请参见下文。

Add-to-app flows with Android Studio are only supported on Android Studio 3.6 with version 42+ of the Flutter plugin for IntelliJ. The Android Studio integration also only supports integrating using a source code Gradle subproject, rather than using AARs. See below for more details on the distinction.

在 Android Studio 打开现有的 Android 项目并点击菜单按钮 File > New > New Module… ，这样就可以创建出一个可以集成的新 Flutter 模块，或者选择导入已有的 Flutter 模块。

Using the File > New > New Module… menu in Android Studio in your existing Android project, you can either create a new Flutter module to integrate, or select an existing Flutter module that was created previously.

如果你想创建一个新的 Flutter 模块，则可以直接在向导窗口中填写模块名称、路径等信息。

If you create a new module, you can use a wizard to select the module name, location, and so on.

此时，Android Studio 插件就会自动为这个 Android 项目配置添加 Flutter 模块作为依赖项，这时集成应用就已准备好进行下一步的构建。

The Android Studio plugin automatically configures your Android project to add your Flutter module as a dependency, and your app is ready to build.

现在，应用程序已经包含了 Flutter 模块作为依赖项，你可以跳转至向 Android 应用中添加 Flutter 页面执行后续步骤。

Your app now includes the Flutter module as a dependency. You can jump to the Adding a Flutter screen to an Android app to follow the next steps.

手动集成

Manual integration

如果想要在不使用 Flutter 的 Android Studio 插件的情况下手动将 Flutter 模块与现有的 Android 应用集成，可以参考以下步骤：

To integrate a Flutter module with an existing Android app manually, without using Flutter’s Android Studio plugin, follow these steps:

创建 Flutter 模块

Create a Flutter module

假设你在 some/path/MyApp 路径下已有一个 Android 应用，并且你希望 Flutter 项目作为同级项目：

Let’s assume that you have an existing Android app at some/path/MyApp, and that you want your Flutter project as a sibling:

$ cd some/path/
$ flutter create -t module --org com.example my_flutter

这会创建一个 some/path/my_flutter/ 的 Flutter 模块项目，其中包含一些 Dart 代码来帮助你入门以及一个隐藏的子文件夹 .android/。 .android 文件夹包含一个 Android 项目，该项目不仅可以帮助你通过 flutter run 运行这个 Flutter 模块的独立应用，而且还可以作为封装程序来帮助引导 Flutter 模块作为可嵌入的 Android 库。

This creates a some/path/my_flutter/ Flutter module project with some Dart code to get you started and an .android/ hidden subfolder. The .android folder contains an Android project that can both help you run a barebones standalone version of your Flutter module via flutter run and it’s also a wrapper that helps bootstrap the Flutter module an embeddable Android library.

提示

将自己的 Android 代码添加到你现有应用程序的项目或插件中，而不是添加到 .android/ 中的模块。在模块的 .android/ 目录中所做的任何更改并不会显示在使用该模块的现有 Android 项目中。

Add custom Android code to your own existing application’s project or a plugin, not to the module in .android/. Changes made in your module’s .android/ directory won’t appear in your existing Android project using the module.

由于 .android/ 目录是自动生成的，因此不需要对它的代码进行版本控制，在新机器上构建模块之前，可以先在 my_flutter 目录中运行 flutter pub get 来重新生成 .android/ 目录，然后再使用 Flutter 模块构建 Android 项目。

Do not source control the .android/ directory since it’s autogenerated. Before building the module on a new machine, run flutter pub get in the my_flutter directory first to regenerate the .android/ directory before building the Android project using the Flutter module.

引入 Java 8

Java 8 requirement

Flutter Android 引擎需要使用到 Java 8 中的新特性。

The Flutter Android engine uses Java 8 features.

在尝试将 Flutter 模块项目集成到宿主 Android 应用之前，请先确保宿主 Android 应用的 build.gradle 文件的 android { } 块中声明了以下源兼容性，例如：

Before attempting to connect your Flutter module project to your host Android app, ensure that your host Android app declares the following source compatibility within your app’s build.gradle file, under the android { } block, such as:

android {
  //...
  compileOptions {
    sourceCompatibility 1.8
    targetCompatibility 1.8
  }
}

将 Flutter module 作为依赖项

Add the Flutter module as a dependency

接下来，将 Flutter 模块添加为 Gradle 中宿主应用程序的依赖项。主要有两种方法实现。 AAR 机制可以为每个 Flutter 模块创建 Android AAR 作为依赖媒介。当你的宿主应用程序开发者不想安装 Flutter SDK 时，这是一个很好方案，但是，如果你想要经常编译，那么每次都需要重新编译一次，该步骤不可避免。

Next, add the Flutter module as a dependency of your existing app in Gradle. There are two ways to achieve this. The AAR mechanism creates generic Android AARs as intermediaries that packages your Flutter module. This is good when your downstream app builders don’t want to have the Flutter SDK installed. But, it adds one more build step if you build frequently.

直接将 Flutter 模块的源码作为子项目的依赖机制是一种便捷的一键式构建方案，但此时需要另外安装 Flutter SDK，这是目前 Android Studio IDE 插件使用的机制。

The source code subproject mechanism is a convenient one-click build process, but requires the Flutter SDK. This is the mechanism used by the Android Studio IDE plugin.

方案 A - 依赖 Android Archive (AAR)

Option A - Depend on the Android Archive (AAR)

这种方式会将 Flutter 库打包成由 AAR 和 POM artifacts 组成的本地 Maven 存储库。这种方案可以使你的团队不需要安装 Flutter SDK 即可编译宿主应用。之后，你可以从本地或远程存储库中分发更新 artifacts。

This option packages your Flutter library as a generic local Maven repository composed of AARs and POMs artifacts. This option allows your team to build the host app without installing the Flutter SDK. You can then distribute the artifacts from a local or remote repository.

假设你在 some/path/my_flutter 下构建 Flutter 模块，执行如下命令：

Let’s assume you built a Flutter module at some/path/my_flutter, and then run:

$ cd some/path/my_flutter
$ flutter build aar

然后，根据屏幕上的提示完成集成操作。

Then, follow the on-screen instructions to integrate.

详细地说，该命令应用于创建（默认情况下创建 debug/profile/release 所有模式）本地存储库，主要包含以下文件：

More specifically, this command creates (by default all debug/profile/release modes) a local repository, with the following files:

build/host/outputs/repo
└── com
    └── example
        └── my_flutter
            ├── flutter_release
            │   ├── 1.0
            │   │   ├── flutter_release-1.0.aar
            │   │   ├── flutter_release-1.0.aar.md5
            │   │   ├── flutter_release-1.0.aar.sha1
            │   │   ├── flutter_release-1.0.pom
            │   │   ├── flutter_release-1.0.pom.md5
            │   │   └── flutter_release-1.0.pom.sha1
            │   ├── maven-metadata.xml
            │   ├── maven-metadata.xml.md5
            │   └── maven-metadata.xml.sha1
            ├── flutter_profile
            │   ├── ...
            └── flutter_debug
                └── ...

要依赖 AAR，宿主应用必须能够找到这些文件。

To depend on the AAR, the host app must be able to find these files.

为此，需要在宿主应用程序中修改 app/build.gradle 文件，使其包含本地存储库和上述依赖项：

To do that, edit app/build.gradle in your host app so that it includes the local repository and the dependency:

android {
  // ...
}

repositories {
  maven {
    url 'some/path/my_flutter/build/host/outputs/repo'
    // This is relative to the location of the build.gradle file
    // if using a relative path.
  }
  maven {
    url 'https://storage.googleapis.com/download.flutter.io'
  }
}

dependencies {
  // ...
  debugImplementation 'com.example.flutter_module:flutter_debug:1.0'
  profileImplementation 'com.example.flutter_module:flutter_profile:1.0'
  releaseImplementation 'com.example.flutter_module:flutter_release:1.0'
}

你的应用程序现在添加了 Flutter 模块作为依赖项，下面，你可以按照向 Android 应用中添加 Flutter 页面中的后续步骤继续操作。

Your app now includes the Flutter module as a dependency. You can follow the next steps in the Adding a Flutter screen to an Android app.

方案 B - 依赖模块的源码

Option B - Depend on the module’s source code

该方式可以使你的 Android 项目和 Flutter 项目能够同步一键式构建。当你需要同时在这两个项目中进行快速迭代时，这种方案非常方便，但是此时，你的团队必须安装 Flutter SDK 才能构建宿主应用程序。

This option enables a one-step build for both your Android project and Flutter project. This option is convenient when you work on both parts simultaneously and rapidly iterate, but your team must install the Flutter SDK to build the host app.

将 Flutter 模块作为子项目添加到宿主应用的 settings.gradle 中：

Include the Flutter module as a subproject in the host app’s settings.gradle:

// Include the host app project.
include ':app'                                    // assumed existing content
setBinding(new Binding([gradle: this]))                                // new
evaluate(new File(                                                     // new
  settingsDir.parentFile,                                              // new
  'my_flutter/.android/include_flutter.groovy'                         // new
))                                                                     // new

假设 my_flutter 和 MyApp 是同级目录。

Assuming my_flutter is a sibling to MyApp.

binding 和 evaluation 脚本可以使 Flutter 模块将其自身（如 :flutter）和该模块使用的所有 Flutter 插件（如 :package_info，:video_player 等）都包含在 settings.gradle 的评估的上下文中。

The binding and script evaluation allows the Flutter module to include itself (as :flutter) and any Flutter plugins used by the module (as :package_info, :video_player, etc) in the evaluation context of your settings.gradle.

在你的应用中引入对 Flutter 模块的依赖：

Introduce an implementation dependency on the Flutter module from your app:

dependencies {
  implementation project(':flutter')
}

此时，你的应用程序已将 Flutter 模块添加为依赖项，下面，你可以按照向 Android 应用中添加 Flutter 页面中的后续步骤继续操作。

Your app now includes the Flutter module as a dependency. You can follow the next steps in the Adding a Flutter screen to an Android app.

在 Android 应用中添加 Flutter 页面

添加一个普通的 Flutter 页面
Add a normal Flutter screen
Add a translucent Flutter screen
- 步骤 1：使用透明的主题
  Step 1: Use a theme with translucency
- 步骤 2：启动透明的 FlutterActivity
  Step 2: Start FlutterActivity with transparency

本指南讲述了如何在一个现有的 Android 应用中添加单个 Flutter 页面。添加到应用中的单个 Flutter 页面可以是不透明的普通页面，也可以是透明的页面。这两种页面的使用都会在本指南中提到。

This guide describes how to add a single Flutter screen to an existing Android app. A Flutter screen can be added as a normal, opaque screen, or as a see-through, translucent screen. Both options are described in this guide.

添加一个普通的 Flutter 页面

Add a normal Flutter screen

Add Flutter Screen Header

步骤 1：在 AndroidManifest.xml 中添加 FlutterActivity

Step 1: Add FlutterActivity to AndroidManifest.xml

Flutter 提供了 FlutterActivity，用于在 Android 应用内部展示一个 Flutter 的交互界面。和其他的 Activity 一样，FlutterActivity 必须在项目的 AndroidManifest.xml 文件中注册。将下边的 XML 代码添加到你的 AndroidManifest.xml 文件中的 application 标签内：

Flutter provides FlutterActivity to display a Flutter experience within an Android app. Like any other Activity, FlutterActivity must be registered in your AndroidManifest.xml. Add the following XML to your AndroidManifest.xml file under your application tag:

<activity
  android:name="io.flutter.embedding.android.FlutterActivity"
  android:theme="@style/LaunchTheme"
  android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
  android:hardwareAccelerated="true"
  android:windowSoftInputMode="adjustResize"
  />

上述代码中的 @style/LaunchTheme 可以替换为想要在你的 FlutterActivity 中使用的其他 Android 主题。主题的选择决定 Android 系统展示框架所使用的颜色，例如 Android 的导航栏，以及 Flutter UI 自身的第一次渲染前 FlutterActivity 的背景色。

The reference to @style/LaunchTheme can be replaced by any Android theme that want to apply to your FlutterActivity. The choice of theme dictates the colors applied to Android’s system chrome, like Android’s navigation bar, and to the background color of the FlutterActivity just before the Flutter UI renders itself for the first time.

步骤 2：加载 FlutterActivity

Step 2: Launch FlutterActivity

在你的清单文件中注册了 FlutterActivity 之后，根据需要，你可以在应用中的任意位置添加打开 FlutterActivity 的代码。下边的代码展示了如何在 OnClickListener 的点击事件中打开 FlutterActivity。

With FlutterActivity registered in your manifest file, add code to launch FlutterActivity from whatever point in your app that you’d like. The following example shows FlutterActivity being launched from an OnClickListener.

Java
Kotlin

myButton.setOnClickListener(new OnClickListener() {
  @Override
  public void onClick(View v) {
    startActivity(
      FlutterActivity.createDefaultIntent(currentActivity)
    );
  }
});

myButton.setOnClickListener {
  startActivity(
    FlutterActivity.createDefaultIntent(this)
  )
}

上述的例子假定了你的 Dart 代码入口是调用 main()，并且你的 Flutter 初始路由是 ‘/’。 Dart 代码入口不能通过 Intent 改变，但是初始路由可以通过 Intent 来修改。下面的例子讲解了如何打开一个自定义 Flutter 初始路由的 FlutterActivity。

The previous example assumes that your Dart entrypoint is called main(), and your initial Flutter route is ‘/’. The Dart entrypoint can’t be changed using Intent, but the initial route can be changed using Intent. The following example demonstrates how to launch a FlutterActivity that initially renders a custom route in Flutter.

Java
Kotlin

myButton.addOnClickListener(new OnClickListener() {
  @Override
  public void onClick(View v) {
    startActivity(
      FlutterActivity
        .withNewEngine()
        .initialRoute("/my_route")
        .build(currentActivity)
      );
  }
});

myButton.setOnClickListener {
  startActivity(
    FlutterActivity
      .withNewEngine()
      .initialRoute("/my_route")
      .build(this)
  )
}

可以用你想要的初始路由替换掉 "/my_route"。

Replace "/my_route" with your desired initial route.

工厂方法 withNewEngine() 可以用于配置一个 FlutterActivity，它会在内部创建一个属于自己的 FlutterEngine 实例，这会有一个明显的初始化时间。另外一种可选的做法是让 FlutterActivity 使用一个预热且缓存的 FlutterEngine，这可以最小化 Flutter 初始化的时间。这种方式接下来会讨论到。

The use of the withNewEngine() factory method configures a FlutterActivity that internally create its own FlutterEngine instance. This comes with a non-trivial initialization time. The alternative approach is to instruct FlutterActivity to use a pre-warmed, cached FlutterEngine, which minimizes Flutter’s initialization time. That approach is discussed next.

步骤 3：（可选）使用缓存的 FlutterEngine

Step 3: (Optional) Use a cached FlutterEngine

每一个 FlutterActivity 默认会创建它自己的 FlutterEngine。每一个 FlutterEngine 会有一个明显的预热时间。这意味着加载一个标准的 FlutterActivity 时，在你的 Flutter 交互页面可见之前会有一个短暂的延迟。想要最小化这个延迟时间，你可以在抵达你的 FlutterActivity 之前，初始化一个 FlutterEngine，然后使用这个已经预热好的 FlutterEngine。

Every FlutterActivity creates its own FlutterEngine by default. Each FlutterEngine has a non-trivial warm-up time. This means that launching a standard FlutterActivity comes with a brief delay before your Flutter experience becomes visible. To minimize this delay, you can warm up a FlutterEngine before arriving at your FlutterActivity, and then you can use your pre-warmed FlutterEngine instead.

要预热一个 FlutterEngine，可以在你的应用中找一个合理的地方实例化一个 FlutterEngine。下面的这个例子是在 Application 类中预先初始化一个 FlutterEngine：

To pre-warm a FlutterEngine, find a reasonable location in your app to instantiate a FlutterEngine. The following example arbitrarily pre-warms a FlutterEngine in the Application class:

Java
Kotlin

public class MyApplication extends Application {
  public FlutterEngine flutterEngine;
  
  @Override
  public void onCreate() {
    super.onCreate();
    // Instantiate a FlutterEngine.
    flutterEngine = new FlutterEngine(this);

    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.getDartExecutor().executeDartEntrypoint(
      DartEntrypoint.createDefault()
    );

    // Cache the FlutterEngine to be used by FlutterActivity.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine);
  }
}

class MyApplication : Application() {
  lateinit var flutterEngine : FlutterEngine

  override fun onCreate() {
    super.onCreate()

    // Instantiate a FlutterEngine.
    flutterEngine = FlutterEngine(this)

    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.dartExecutor.executeDartEntrypoint(
      DartExecutor.DartEntrypoint.createDefault()
    )

    // Cache the FlutterEngine to be used by FlutterActivity.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine)
  }
}

传给 FlutterEngineCache 的 ID 可以是你想要的任何名称。确保 FlutterActivity 或 FlutterFragment 在使用缓存的 FlutterEngine 时，传递了同样的 ID。基于缓存的 FlutterEngine 来使用 FlutterActivity 会在后续讨论到。

The ID passed to the FlutterEngineCache can be whatever you want. Make sure that you pass the same ID to any FlutterActivity or FlutterFragment that should use the cached FlutterEngine. Using FlutterActivity with a cached FlutterEngine is discussed next.

提示

要预热一个 FlutterEngine，你必须执行一个 Dart 入口。切记当 executeDartEntrypoint() 方法调用时，你的 Dart 入口方法就会开始执行。如果你的 Dart 入口调用了 runApp() 来运行一个 Flutter 应用，那么你的 Flutter 应用会像是运行在一个大小为零的窗口中，直至 FlutterEngine 附属到一个 FlutterActivity，FlutterFragment 或 FlutterView。请确保你的应用在开始预热到你展示 Flutter 内容中间的这段时间里表现正常。

To warm up a FlutterEngine, you must execute a Dart entrypoint. Keep in mind that the moment executeDartEntrypoint() is invoked, your Dart entrypoint method begins executing. If your Dart entrypoint invokes runApp() to run a Flutter app, then your Flutter app behaves as if it were running in a window of zero size until this FlutterEngine is attached to a FlutterActivity, FlutterFragment, or FlutterView. Make sure that your app behaves appropriately between the time you warm it up and the time you display Flutter content.

要使用预热且缓存的 FlutterEngine 时，让你的 FlutterActivity 从缓存中获取 FlutterEngine，而不是创建一个新的。可以使用 FlutterActivity 的 withCachedEngine() 方法来实现：

With a pre-warmed, cached FlutterEngine, you now need to instruct your FlutterActivity to use the cached FlutterEngine instead of creating a new one. To accomplish this, use FlutterActivity’s withCachedEngine() builder:

Java
Kotlin

myButton.addOnClickListener(new OnClickListener() {
  @Override
  public void onClick(View v) {
    startActivity(
      FlutterActivity
        .withCachedEngine("my_engine_id")
        .build(currentActivity)
      );
  }
});

myButton.setOnClickListener {
  startActivity(
    FlutterActivity
      .withCachedEngine("my_engine_id")
      .build(this)
  )
}

当使用 withCachedEngine() 方法时，传递你缓存对应 FlutterEngine 时用的相同 ID。

When using the withCachedEngine() factory method, pass the same ID that you used when caching the desired FlutterEngine.

现在，当你加载 FlutterActivity 时，在展示 Flutter 内容前的延迟会明显降低。

Now, when you launch FlutterActivity, there is significantly less delay in the display of Flutter content.

提示

当使用一个缓存的 FlutterEngine 时， FlutterEngine 会比展示它的 FlutterActivity 或 FlutterFragment 存活得更久。切记，Dart 代码会在你预热 FlutterEngine 时就开始执行，并且在你的 FlutterActivity 或 FlutterFragment 销毁后继续运行。要停止代码运行和清理相关资源，可以从 FlutterEngineCache 中获取你的 FlutterEngine，然后使用 FlutterEngine.destroy() 来销毁 FlutterEngine。

When using a cached FlutterEngine, that FlutterEngine outlives any FlutterActivity or FlutterFragment that displays it. Keep in mind that Dart code begins executing as soon as you pre-warm the FlutterEngine, and continues executing after the destruction of your FlutterActivity/FlutterFragment. To stop executing and clear resources, obtain your FlutterEngine from the FlutterEngineCache and destroy the FlutterEngine with FlutterEngine.destroy().

提示

运行时的性能考量并不是你会预热和缓存一个 FlutterEngine 的唯一原因。一个预热的 FlutterEngine 会独立于 FlutterActivity 执行 Dart 代码，即一个 FlutterEngine 可以在任意时刻用于执行任意代码。非 UI 的应用逻辑可以在 FlutterEngine 中执行，例如网络请求和数据缓存，以及在 Service 中或其他地方的后台行为。当使用 FlutterEngine 在后台执行任务时，确保满足 Android 对于后台执行的所有限制。

Runtime performance isn’t the only reason that you might pre-warm and cache a FlutterEngine. A pre-warmed FlutterEngine executes Dart code independent from a FlutterActivity, which allows such a FlutterEngine to be used to execute arbitrary Dart code at any moment. Non-UI application logic can be executed in a FlutterEngine, like networking and data caching, and in background behavior within a Service or elsewhere. When using a FlutterEngine to execute behavior in the background, be sure to adhere to all Android restrictions on background execution.

Initial route with a cached engine

当配置一个使用新 FlutterEngine 的 FlutterActivity 或者 FlutterFragment 时，会使用到初始路由的概念。但是，使用缓存中的 Flutter 引擎时， FlutterActivity 或者 FlutterFragment 则没有涉及初始路由的概念。这是因为被缓存的引擎理论上已经执行了 Dart 代码，在这时配置初始路由已经太迟了。

The concept of an initial route is available when configuring a FlutterActivity or a FlutterFragment with a new FlutterEngine. However, FlutterActivity and FlutterFragment don’t offer the concept of an initial route when using a cached engine. This is because a cached engine is expected to already be running Dart code, which means it’s too late to configure the initial route.

开发者如果想要让缓存中的引擎从自定义的初始路由开始运行，那么可以执行 Dart 入口前，为缓存的 FlutterEngine 配置自定义的初始路由。如下面这个例子：

Developers that would like their cached engine to begin with a custom initial route can configure their cached FlutterEngine to use a custom initial route just before executing the Dart entrypoint. The following example demonstrates the use of an initial route with a cached engine:

Java
Kotlin

public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    // Instantiate a FlutterEngine.
    flutterEngine = new FlutterEngine(this);
    // Configure an initial route.
    flutterEngine.getNavigationChannel().setInitialRoute("your/route/here");
    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.getDartExecutor().executeDartEntrypoint(
      DartEntrypoint.createDefault()
    );
    // Cache the FlutterEngine to be used by FlutterActivity or FlutterFragment.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine);
  }
}

class MyApplication : Application() {
  lateinit var flutterEngine : FlutterEngine
  override fun onCreate() {
    super.onCreate()
    // Instantiate a FlutterEngine.
    flutterEngine = FlutterEngine(this)
    // Configure an initial route.
    flutterEngine.navigationChannel.setInitialRoute("your/route/here");
    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.dartExecutor.executeDartEntrypoint(
      DartExecutor.DartEntrypoint.createDefault()
    )
    // Cache the FlutterEngine to be used by FlutterActivity or FlutterFragment.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine)
  }
}

通过设置导航通道中的初始路由，会让关联的 FlutterEngine 在 runApp() 方法首次执行后，展示已配置的路由页面。

By setting the initial route of the navigation channel, the associated FlutterEngine displays the desired route upon initial execution of the runApp() Dart function.

在 runApp() 的首次执行之后，修改导航通道中的初始路由属性是不会生效的。想要在不同的 Activity 和 Fragment 之间使用同一个 FlutterEngine，并且在其展示时切换不同的路由，开发者需要设置一个方法通道，来显式地通知他们的 Dart 代码切换 Navigator 路由。

Changing the initial route property of the navigation channel after the initial execution of runApp() has no effect. Developers who would like to use the same FlutterEngine between different Activitys and Fragments and switch the route between those displays need to setup a method channel and explicitly instruct their Dart code to change Navigator routes.

Add a translucent Flutter screen

Add Flutter Screen With Translucency Header

大部分的全屏 Flutter 交互页面是不透明的。但是，一些应用可能会发布一个类似模态框的 Flutter 页面，例如，一个对话框或者底部工作表。 Flutter 默认支持透明的 FlutterActivity。

Most full-screen Flutter experiences are opaque. However, some apps would like to deploy a Flutter screen that looks like a modal, for example, a dialog or bottom sheet. Flutter supports translucent FlutterActivitys out of the box.

要将你的 FlutterActivity 设置为透明，在创建和加载 FlutterActivity 的常规步骤中做如下的变更。

To make your FlutterActivity translucent, make the following changes to the regular process of creating and launching a FlutterActivity.

步骤 1：使用透明的主题

Step 1: Use a theme with translucency

Android 需要一个特殊的主题属性来让 Activity 以一个透明的背景渲染。使用如下属性来创建或者修改一个 Android 主题：

Android requires a special theme property for Activitys that render with a translucent background. Create or update an Android theme with the following property:

<style name="MyTheme" parent="@style/MyParentTheme">
  <item name="android:windowIsTranslucent">true</item>
</style>

然后，将透明主题应用到你的 FlutterActivity。

Then, apply the translucent theme to your FlutterActivity.

<activity
  android:name="io.flutter.embedding.android.FlutterActivity"
  android:theme="@style/MyTheme"
  android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
  android:hardwareAccelerated="true"
  android:windowSoftInputMode="adjustResize"
  />

现在你的 FlutterActivity 已经支持透明化。下一步，你需要在打开 FlutterActivity 时显式启用透明模式。

Your FlutterActivity now supports translucency. Next, you need to launch your FlutterActivity with explicit transparency support.

步骤 2：启动透明的 FlutterActivity

Step 2: Start FlutterActivity with transparency

要打开透明背景的 FlutterActivity，需要把对应的 BackgroundMode 传递给 IntentBuilder：

To launch your FlutterActivity with a transparent background, pass the appropriate BackgroundMode to the IntentBuilder:

Java
Kotlin

// Using a new FlutterEngine.
startActivity(
  FlutterActivity
    .withNewEngine()
    .backgroundMode(FlutterActivityLaunchConfigs.BackgroundMode.transparent)
    .build(context)
);

// Using a cached FlutterEngine.
startActivity(
  FlutterActivity
    .withCachedEngine("my_engine_id")
    .backgroundMode(FlutterActivityLaunchConfigs.BackgroundMode.transparent)
    .build(context)
);

// Using a new FlutterEngine.
startActivity(
  FlutterActivity
    .withNewEngine()
    .backgroundMode(FlutterActivityLaunchConfigs.BackgroundMode.transparent)
    .build(this)
);

// Using a cached FlutterEngine.
startActivity(
  FlutterActivity
    .withCachedEngine("my_engine_id")
    .backgroundMode(FlutterActivityLaunchConfigs.BackgroundMode.transparent)
    .build(this)
);

现在你的 FlutterAcivity 的背景已经是透明的了。

You now have a FlutterActivity with a transparent background.

向 Android 应用中添加 Flutter Fragment

使用新的 FlutterEngine 向 Activity 中添加 FlutterFragment
Add a FlutterFragment to an Activity with a new FlutterEngine
使用预热的 FlutterEngine
Using a pre-warmed FlutterEngine
- 缓存引擎中的初始路由
  Initial route with a cached engine
展示闪屏页
Display a splash screen
指定 Flutter 运行的初始路由
Run Flutter with a specified initial route
指定 Flutter 运行的入口
Run Flutter from a specified entrypoint
控制 FlutterFragment 的渲染模式
Control FlutterFragment’s render mode
展示透明的 FlutterFragment
Display a FlutterFragment with transparency
FlutterFragment 与其 Activity 之间的关系
The relationship between FlutterFragment and its Activity

Add Flutter Fragment Header

本篇指南介绍如何向一个现有的 Android 应用中添加 Flutter Fragment。在 Android 开发中，一个 Fragment 代表了一块较大的模块化 UI。 Fragment 可能被用来展示滑动抽屉、标签内容和 ViewPager 中的页面，或者在单 Activity 应用中，Fragment 可能仅代表正常的屏幕内容。 Flutter 提供了FlutterFragment，以便于开发者们可以在任何使用常规 Fragment 的地方呈现 Flutter 的内容。

This guide describes how to add a Flutter Fragment to an existing Android app. In Android, a Fragment represents a modular piece of a larger UI. A Fragment might be used to present a sliding drawer, tabbed content, a page in a ViewPager, or it might simply represent a normal screen in a single-Activity app. Flutter provides a FlutterFragment so that developers can present a Flutter experience any place that they can use a regular Fragment.

如果 Activity 同样适用于您的应用需求，可以考虑使用 FlutterActivity 而非 FlutterFragment，前者更加快捷易用。

If an Activity is equally applicable for your application needs, consider using a FlutterActivity instead of a FlutterFragment, which is quicker and easier to use.

FlutterFragment 允许开发者在 Fragment 中控制以下 Flutter 的开发细节：

FlutterFragment allows developers to control the following details of the Flutter experience within the Fragment:

Flutter 初始路由
Initial Flutter route
将要执行的 Dart 入口
Dart entrypoint to execute
非透明或者透明的背景
Opaque vs translucent background
FlutterFragment 是否能控制它外层的 Activity
Whether FlutterFragment should control its surrounding Activity
使用新的还是缓存的 FlutterEngine
Whether a new FlutterEngine or a cached FlutterEngine should be used

FlutterFragment 还提供了一些回调事件，这些回调必须由它所在的 Activity 触发执行。这些回调允许 Flutter 适时地响应一些系统事件。

FlutterFragment also comes with a number of calls that must be forwarded from its surrounding Activity. These calls allow Flutter to react appropriately to OS events.

这篇指南介绍了 FlutterFragment 的所有使用方式和使用要求。

All varieties of FlutterFragment, and its requirements, are described in this guide.

使用新的 `FlutterEngine` 向 `Activity` 中添加 `FlutterFragment`

Add a `FlutterFragment` to an `Activity` with a new `FlutterEngine`

使用 FlutterFragment 的第一步是将其添加进宿主 Activity。

The first thing to do to use a FlutterFragment is to add it to a host Activity.

要向宿主 Activity 中添加 FlutterFragment，需要在 Activity 的 onCreate() 或者其它合适的地方，实例化 FlutterFragment 并且与 Activity 绑定。

To add a FlutterFragment to a host Activity, instantiate and attach an instance of FlutterFragment in onCreate() within the Activity, or at another time that works for your app:

Java
Kotlin

public class MyActivity extends FragmentActivity {
    // Define a tag String to represent the FlutterFragment within this
    // Activity's FragmentManager. This value can be whatever you'd like.
    private static final String TAG_FLUTTER_FRAGMENT = "flutter_fragment";

    // Declare a local variable to reference the FlutterFragment so that you
    // can forward calls to it later.
    private FlutterFragment flutterFragment;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Inflate a layout that has a container for your FlutterFragment.
        // For this example, assume that a FrameLayout exists with an ID of
        // R.id.fragment_container.
        setContentView(R.layout.my_activity_layout);

        // Get a reference to the Activity's FragmentManager to add a new
        // FlutterFragment, or find an existing one.
        FragmentManager fragmentManager = getSupportFragmentManager();

        // Attempt to find an existing FlutterFragment,
        // in case this is not the first time that onCreate() was run.
        flutterFragment = (FlutterFragment) fragmentManager
            .findFragmentByTag(TAG_FLUTTER_FRAGMENT);

        // Create and attach a FlutterFragment if one does not exist.
        if (flutterFragment == null) {
            flutterFragment = FlutterFragment.createDefault();

            fragmentManager
                .beginTransaction()
                .add(
                    R.id.fragment_container,
                    flutterFragment,
                    TAG_FLUTTER_FRAGMENT
                )
                .commit();
        }
    }
}

class MyActivity : FragmentActivity() {
  companion object {
    // Define a tag String to represent the FlutterFragment within this
    // Activity's FragmentManager. This value can be whatever you'd like.
    private const val TAG_FLUTTER_FRAGMENT = "flutter_fragment"
  }

  // Declare a local variable to reference the FlutterFragment so that you
  // can forward calls to it later.
  private var flutterFragment: FlutterFragment? = null

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Inflate a layout that has a container for your FlutterFragment. For
    // this example, assume that a FrameLayout exists with an ID of
    // R.id.fragment_container.
    setContentView(R.layout.my_activity_layout)

    // Get a reference to the Activity's FragmentManager to add a new
    // FlutterFragment, or find an existing one.
    val fragmentManager: FragmentManager = supportFragmentManager

    // Attempt to find an existing FlutterFragment, in case this is not the
    // first time that onCreate() was run.
    flutterFragment = fragmentManager
      .findFragmentByTag(TAG_FLUTTER_FRAGMENT) as FlutterFragment?

    // Create and attach a FlutterFragment if one does not exist.
    if (flutterFragment == null) {
      var newFlutterFragment = FlutterFragment.createDefault()
      flutterFragment = newFlutterFragment
      fragmentManager
        .beginTransaction()
        .add(
          R.id.fragment_container,
          newFlutterFragment,
          TAG_FLUTTER_FRAGMENT
        )
        .commit()
    }
  }
}

上面的代码会以 main() 为 Dart 入口函数， / 为初始路由，并使用新的 FlutterEngine，能够正确渲染出 Flutter UI。但是，这些代码还无法使 Flutter 如预期一样完全正常地工作。 Flutter 依赖操作系统的各种信号，这些信号必须通过宿主 Activity 发送到 FlutterFragment 中。下面的示例展示了这些系统回调：

The previous code is sufficient to render a Flutter UI that begins with a call to your main() Dart entrypoint, an initial Flutter route of /, and a new FlutterEngine. However, this code is not sufficient to achieve all expected Flutter behavior. Flutter depends on various OS signals that must be forwarded from your host Activity to FlutterFragment. These calls are shown in the following example:

Java
Kotlin

public class MyActivity extends FragmentActivity {
    @Override
    public void onPostResume() {
        super.onPostResume();
        flutterFragment.onPostResume();
    }

    @Override
    protected void onNewIntent(@NonNull Intent intent) {
        flutterFragment.onNewIntent(intent);
    }

    @Override
    public void onBackPressed() {
        flutterFragment.onBackPressed();
    }

    @Override
    public void onRequestPermissionsResult(
        int requestCode,
        @NonNull String[] permissions,
        @NonNull int[] grantResults
    ) {
        flutterFragment.onRequestPermissionsResult(
            requestCode,
            permissions,
            grantResults
        );
    }

    @Override
    public void onUserLeaveHint() {
        flutterFragment.onUserLeaveHint();
    }

    @Override
    public void onTrimMemory(int level) {
        super.onTrimMemory(level);
        flutterFragment.onTrimMemory(level);
    }
}

class MyActivity : FragmentActivity() {
  override fun onPostResume() {
    super.onPostResume()
    flutterFragment!!.onPostResume()
  }

  override fun onNewIntent(@NonNull intent: Intent) {
    flutterFragment!!.onNewIntent(intent)
  }

  override fun onBackPressed() {
    flutterFragment!!.onBackPressed()
  }

  override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<String?>,
    grantResults: IntArray
  ) {
    flutterFragment!!.onRequestPermissionsResult(
      requestCode,
      permissions,
      grantResults
    )
  }

  override fun onUserLeaveHint() {
    flutterFragment!!.onUserLeaveHint()
  }

  override fun onTrimMemory(level: Int) {
    super.onTrimMemory(level)
    flutterFragment!!.onTrimMemory(level)
  }
}

随着 OS 信号传递到 Flutter，您的 FlutterFragment 可以如预期正常工作。现在可以尝试将 FlutterFragment 添加进您的 Android 应用了。

With the OS signals forwarded to Flutter, your FlutterFragment works as expected. You have now added a FlutterFragment to your existing Android app.

使用新的 FlutterEngine 是最简单的集成方式，但是会存在一段明显的初始化时间，此时，在 Flutter 初始化和首次渲染完成之前会出现短暂的白屏。使用缓存、预热的 FlutterEngine 则可以避免上述的大部分耗时，下面我们将讨论这些内容。

The simplest integration path uses a new FlutterEngine, which comes with a non-trivial initialization time, leading to a blank UI until Flutter is initialized and rendered the first time. Most of this time overhead can be avoided by using a cached, pre-warmed FlutterEngine, which is discussed next.

使用预热的 `FlutterEngine`

Using a pre-warmed `FlutterEngine`

默认情况下，FlutterFragment 会创建它自己的 FlutterEngine 实例，同时也需要不少的启动时间。这就意味着您的用户会看到短暂的白屏。通过使用已存在的、预热的 FlutterEngine 就可以大幅度减少启动的耗时。

By default, a FlutterFragment creates its own instance of a FlutterEngine, which requires non-trivial warm-up time. This means your user sees a blank Fragment for a brief moment. You can mitigate most of this warm-up time by using an existing, pre-warmed instance of FlutterEngine.

要在 FlutterFragment 中使用预热 FlutterEngine，可以使用工厂方法 withCachedEngine() 实例化 FlutterFragment。

To use a pre-warmed FlutterEngine in a FlutterFragment, instantiate a FlutterFragment with the withCachedEngine() factory method.

Java
Kotlin

// Somewhere in your app, before your FlutterFragment is needed,
// like in the Application class ...
// Instantiate a FlutterEngine.
FlutterEngine flutterEngine = new FlutterEngine(context);

// Start executing Dart code in the FlutterEngine.
flutterEngine.getDartExecutor().executeDartEntrypoint(
    DartEntrypoint.createDefault()
);

// Cache the pre-warmed FlutterEngine to be used later by FlutterFragment.
FlutterEngineCache
  .getInstance()
  .put("my_engine_id", flutterEngine);

FlutterFragment.withCachedEngine("my_engine_id").build();

// Somewhere in your app, before your FlutterFragment is needed,
// like in the Application class ...
// Instantiate a FlutterEngine.
val flutterEngine = FlutterEngine(context)

// Start executing Dart code in the FlutterEngine.
flutterEngine.getDartExecutor().executeDartEntrypoint(
    DartEntrypoint.createDefault()
)

// Cache the pre-warmed FlutterEngine to be used later by FlutterFragment.
FlutterEngineCache
  .getInstance()
  .put("my_engine_id", flutterEngine)

FlutterFragment.withCachedEngine("my_engine_id").build()

FlutterFragment 内部可访问 FlutterEngineCache，并且可以根据传递给 withCachedEngine() 的 ID 获取预热的 FlutterEngine。

FlutterFragment internally knows about FlutterEngineCache and retrieves the pre-warmed FlutterEngine based on the ID given to withCachedEngine().

如上所示，通过提供预热的 FlutterEngine，您的应用将以最快速度渲染出第一帧。

By providing a pre-warmed FlutterEngine, as previously shown, your app renders the first Flutter frame as quickly as possible.

缓存引擎中的初始路由

public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    // Instantiate a FlutterEngine.
    flutterEngine = new FlutterEngine(this);
    // Configure an initial route.
    flutterEngine.getNavigationChannel().setInitialRoute("your/route/here");
    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.getDartExecutor().executeDartEntrypoint(
      DartEntrypoint.createDefault()
    );
    // Cache the FlutterEngine to be used by FlutterActivity or FlutterFragment.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine);
  }
}

class MyApplication : Application() {
  lateinit var flutterEngine : FlutterEngine
  override fun onCreate() {
    super.onCreate()
    // Instantiate a FlutterEngine.
    flutterEngine = FlutterEngine(this)
    // Configure an initial route.
    flutterEngine.navigationChannel.setInitialRoute("your/route/here");
    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.dartExecutor.executeDartEntrypoint(
      DartExecutor.DartEntrypoint.createDefault()
    )
    // Cache the FlutterEngine to be used by FlutterActivity or FlutterFragment.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine)
  }
}

通过设置导航通道中的初始路由，会让关联的 FlutterEngine 在 runApp() 方法首次执行后，展示已配置的路由页面。

By setting the initial route of the navigation channel, the associated FlutterEngine displays the desired route upon initial execution of the runApp() Dart function.

展示闪屏页

Display a splash screen

即使使用了预热的 FlutterEngine，第一次展示 Flutter 的内容仍然需要一些时间。为了更进一步提升用户体验，Flutter 支持在第一帧渲染完成之前展示闪屏页。关于如何展示闪屏页的详细说明，请参阅这篇闪屏页指南。

The initial display of Flutter content requires some wait time, even if a pre-warmed FlutterEngine is used. To help improve the user experience around this brief waiting period, Flutter supports the display of a splash screen until Flutter renders its first frame. For instructions about how to show a splash screen, see the splash screen guide.

指定 Flutter 运行的初始路由

Run Flutter with a specified initial route

一个 Android 应用中可能包含很多独立的 Flutter 界面，这些界面显示在不同的 FlutterFragment 上，每个 FlutterFragment 的 FlutterEngine 也是独立的。在这些情况下，每个 Flutter 界面通过不同的初始路由（除 / 以外的路由）启动是很正常的。为此，FlutterFragment 的 Builder 允许指定一个您希望的初始路由，如下所示：

An Android app might contain many independent Flutter experiences, running in different FlutterFragments, with different FlutterEngines. In these scenarios, it’s common for each Flutter experience to begin with different initial routes (routes other than /). To facilitate this, FlutterFragment’s Builder allows you to specify a desired initial route, as shown:

Java
Kotlin

// With a new FlutterEngine.
FlutterFragment flutterFragment = FlutterFragment.withNewEngine()
    .initialRoute("myInitialRoute/")
    .build();

// With a new FlutterEngine.
val flutterFragment = FlutterFragment.withNewEngine()
    .initialRoute("myInitialRoute/")
    .build()

指定 Flutter 运行的入口

Run Flutter from a specified entrypoint

和变化的初始路由类似，不同的 FlutterFragment 可能需要执行不同的 Dart 代码入口。正常的 Flutter 应用中，只会有一个 main() 入口，但是您也可以定义不同的入口。

Similar to varying initial routes, different FlutterFragments may want to execute different Dart entrypoints. In a typical Flutter app, there is only one Dart entrypoint: main(), but you can define other entrypoints.

FlutterFragment 支持指定需要的 Dart 入口以运行对应的 Flutter 界面。下面的代码展示了如何在构建 FlutterFragment 时指定一个入口。

FlutterFragment supports specification of the desired Dart entrypoint to execute for the given Flutter experience. To specify an entrypoint, build FlutterFragment, as shown:

Java
Kotlin

FlutterFragment flutterFragment = FlutterFragment.withNewEngine()
    .dartEntrypoint("mySpecialEntrypoint")
    .build();

val flutterFragment = FlutterFragment.withNewEngine()
    .dartEntrypoint("mySpecialEntrypoint")
    .build()

这里，FlutterFragment 的配置会将 Dart 入口的执行函数设置为 mySpecialEntrypoint()。需要注意的是，括号 () 不包含在 dartEntrypoint 的 String 类型的参数中。

The FlutterFragment configuration results in the execution of a Dart entrypoint called mySpecialEntrypoint(). Notice that the parentheses () are not included in the dartEntrypoint String name.

控制 `FlutterFragment` 的渲染模式

Control `FlutterFragment`’s render mode

FlutterFragment 可以选择使用 SurfaceView 或者 TextureView 来渲染其内容。默认配置的 SurfaceView 在性能上明显好于 TextureView。然而，SurfaceView 无法插入到 Android 的 View 层级之中。 SurfaceView 在视图层级中必须是最底层的 View 或者最顶层的 View。此外，在 Android N 之前，SurfaceView 无法用于制作动画，因为它们的布局和渲染无法和视图层级中的其它 View 同步。如果上述这些用例之一在您的应用需求之中，您需要使用 TextureView 替换 SurfaceView。要选择 TextureView，可以在构建 FlutterFragment 时指定 RenderMode 为 texture：

FlutterFragment can either use a SurfaceView to render its Flutter content, or it can use a TextureView. The default is SurfaceView, which is significantly better for performance than TextureView. However, SurfaceView can’t be interleaved in the middle of an Android View hierarchy. A SurfaceView must either be the bottommost View in the hierarchy, or the topmost View in the hierarchy. Additionally, on Android versions before Android N, SurfaceViews can’t be animated because their layout and rendering aren’t synchronized with the rest of the View hierarchy. If either of these use cases are requirements for your app, then you need to use TextureView instead of SurfaceView. Select a TextureView by building a FlutterFragment with a texture RenderMode:

Java
Kotlin

// With a new FlutterEngine.
FlutterFragment flutterFragment = FlutterFragment.withNewEngine()
    .renderMode(FlutterView.RenderMode.texture)
    .build();

// With a cached FlutterEngine.
FlutterFragment flutterFragment = FlutterFragment.withCachedEngine("my_engine_id")
    .renderMode(FlutterView.RenderMode.texture)
    .build();

// With a new FlutterEngine.
val flutterFragment = FlutterFragment.withNewEngine()
    .renderMode(FlutterView.RenderMode.texture)
    .build()

// With a cached FlutterEngine.
val flutterFragment = FlutterFragment.withCachedEngine("my_engine_id")
    .renderMode(FlutterView.RenderMode.texture)
    .build()

使用上面展示的代码配置，FlutterFragment 可以将它的 UI 渲染为 TextureView。

Using the configuration shown, the resulting FlutterFragment renders its UI to a TextureView.

展示透明的 `FlutterFragment`

Display a `FlutterFragment` with transparency

默认情况下，FlutterFragment 使用 SurfaceView 渲染且背景不透明。（参考「控制 FlutterFragment 的渲染模式」）任何未经 Flutter 绘制的像素在背景中都是黑色的。出于性能方面的考虑，我们优先选择使用不透明的背景进行渲染。渲染透明的 Flutter 界面在 Android 平台上会产生性能方面的负面影响。但是许多设计都需要 Flutter 界面中包含透明的像素以显示底层的 Android UI。因此，Flutter 支持 FlutterFragment 半透明。

By default, FlutterFragment renders with an opaque background, using a SurfaceView. (See “Control FlutterFragment’s render mode.”) That background is black for any pixels that aren’t painted by Flutter. Rendering with an opaque background is the preferred rendering mode for performance reasons. Flutter rendering with transparency on Android negatively affects performance. However, there are many designs that require transparent pixels in the Flutter experience that show through to the underlying Android UI. For this reason, Flutter supports translucency in a FlutterFragment.

提示 Both SurfaceView and TextureView support transparency. However, when a SurfaceView is instructed to render with transparency, it positions itself at a higher z-index than all other Android Views, which means it appears above all other Views. This is a limitation of SurfaceView. If it’s acceptable to render your Flutter experience on top of all other content, then FlutterFragment’s default RenderMode of surface is the RenderMode that you should use. However, if you need to display Android Views both above and below your Flutter experience, then you must specify a RenderMode of texture. See “Control FlutterFragment’s render mode” for information about controlling the RenderMode.

SurfaceView 和 TextureView 都支持透明。但是当 SurfaceView 以透明模式渲染时，它的 Z 轴高度会超过其它所有 Android View ，这意味着 SurfaceView 会展示在其它所有 View 之上。这是 SurfaceView 自身的限制。如果可以接受您的 Flutter 内容渲染在其它所有内容之上，应该使用默认的 surface 作为 FlutterFragment 的 RenderMode 的配置。但是如果需要在 Flutter 内容的上方和下方展示 Android View，您必须指定 RenderMode 为 texture。

要启动一个透明的 FlutterFragment，可以使用以下方式进行构建：

To enable transparency for a FlutterFragment, build it with the following configuration:

Java
Kotlin

// Using a new FlutterEngine.
FlutterFragment flutterFragment = FlutterFragment.withNewEngine()
    .transparencyMode(FlutterView.TransparencyMode.transparent)
    .build();

// Using a cached FlutterEngine.
FlutterFragment flutterFragment = FlutterFragment.withCachedEngine("my_engine_id")
    .transparencyMode(FlutterView.TransparencyMode.transparent)
    .build();

// Using a new FlutterEngine.
val flutterFragment = FlutterFragment.withNewEngine()
    .transparencyMode(FlutterView.TransparencyMode.transparent)
    .build()

// Using a cached FlutterEngine.
val flutterFragment = FlutterFragment.withCachedEngine("my_engine_id")
    .transparencyMode(FlutterView.TransparencyMode.transparent)
    .build()

`FlutterFragment` 与其 `Activity` 之间的关系

The relationship between `FlutterFragment` and its `Activity`

一些应用选择使用 Fragment 作为整个 Android 屏幕内容。在这些应用里，Fragment 可能会需要控制一些系统属性，例如 Android 的状态栏、导航栏以及屏幕方向。

Some apps choose to use Fragments as entire Android screens. In these apps, it would be reasonable for a Fragment to control system chrome like Android’s status bar, navigation bar, and orientation.

Fullscreen Flutter

在其它应用中，Fragment 通常只是整个 UI 的一部分。 FlutterFragment 可能用于实现抽屉、视频播放器或卡片的内容。在这些情况下，FlutterFragment 就不应当影响 Android 的系统属性，因为同一个 Window 中还有其它 UI 组件。

In other apps, Fragments are used to represent only a portion of a UI. A FlutterFragment might be used to implement the inside of a drawer, a video player, or a single card. In these situations, it would be inappropriate for the FlutterFragment to affect Android’s system chrome because there are other UI pieces within the same Window.

Flutter as Partial UI

FlutterFragment 自身包含一种特性，可以用于决定 FlutterFragment 是否应该控制宿主 Activity，或者只影响自身行为。要预防 FlutterFragment 将其 Activity 暴露给 Flutter 插件，以免 Flutter 控制 Activity 的系统 UI，可以使用 FlutterFragment 的 Builder 中的 shouldAttachEngineToActivity() 方法。如下所示：

FlutterFragment comes with a concept that helps differentiate between the case when a FlutterFragment should be able to control its host Activity, and the cases when a FlutterFragment should only affect its own behavior. To prevent a FlutterFragment from exposing its Activity to Flutter plugins, and to prevent Flutter from controlling the Activity’s system UI, use the shouldAttachEngineToActivity() method in FlutterFragment’s Builder, as shown:

Java
Kotlin

// Using a new FlutterEngine.
FlutterFragment flutterFragment = FlutterFragment.withNewEngine()
    .shouldAttachEngineToActivity(false)
    .build();

// Using a cached FlutterEngine.
FlutterFragment flutterFragment = FlutterFragment.withCachedEngine("my_engine_id")
    .shouldAttachEngineToActivity(false)
    .build();

// Using a new FlutterEngine.
val flutterFragment = FlutterFragment.withNewEngine()
    .shouldAttachEngineToActivity(false)
    .build()

// Using a cached FlutterEngine.
val flutterFragment = FlutterFragment.withCachedEngine("my_engine_id")
    .shouldAttachEngineToActivity(false)
    .build()

传递 false 给 Builder 的 shouldAttachEngineToActivity() 方法，可防止 Flutter 与所属的 Activity 交互。默认值为 true，此时允许 Flutter 和 Flutter 插件与 Activity 交互。

Passing false to the shouldAttachEngineToActivity() Builder method prevents Flutter from interacting with the surrounding Activity. The default value is true, which allows Flutter and Flutter plugins to interact with the surrounding Activity.

Adding a Flutter View to an Android app

A sample
General approach
- APIs to implement

Integrating via a FlutterView requires a bit more work than via FlutterActivity and FlutterFragment previously described.

Fundamentally, the Flutter framework on the Dart side requires access to various activity-level events and lifecycles to function. Since the FlutterView (which is an android.view.View) can be added to any activity which is owned by the developer’s application and since the FlutterView doesn’t have access to activity level events, the developer must bridge those connections manually to the FlutterEngine.

How you choose to feed your application’s activities’ events to the FlutterView will be specific to your application.

A sample

Add Flutter View sample video

Unlike the guides for FlutterActivity and FlutterFragment, the FlutterView integration could be better demonstrated with a sample project.

A sample project is at https://github.com/flutter/samples/tree/master/add_to_app/android_view to document a simple FlutterView integration where FlutterViews are used for some of the cells in a RecycleView list of cards as seen in the gif above.

General approach

The general gist of the FlutterView-level integration is that you must recreate the various interactions between the your Activity, the FlutterView and the FlutterEngine present in the FlutterActivityAndFragmentDelegate in your own application’s code. The connections made in the FlutterActivityAndFragmentDelegate are done automatically when using a FlutterActivity or a FlutterFragment, but since the FlutterView in this case is being added to an Activity or Fragment in your application, you must recreate the connections manually. Otherwise, the FlutterView will not render anything or have other missing functionalities.

A sample FlutterViewEngine class shows one such possible implementation of an application-specific connection between an Activity, a FlutterView and a FlutterEngine.

APIs to implement

The absolute minimum implementation needed for Flutter to draw anything at all is to:

Call attachToFlutterEngine when the FlutterView is added to a resumed Activity’s view hierarchy and is visible; and
Call appIsResumed on the FlutterEngine’s lifecycleChannel field when the Activity hosting the FlutterView is visible.

The reverse detachFromFlutterEngine and other lifecycle methods on the LifecycleChannel class must also be called to not leak resources when the FlutterView or Activity is no longer visible.

In addition, see the remaining implementation in the FlutterViewEngine demo class or in the FlutterActivityAndFragmentDelegate to ensure a correct functioning of other features such as clipboards, system UI overlay, plugins etc.

在混合应用中管理 plugin 和依赖

A. Simple scenario
B. Plugins needing project edits
C. Merging libraries

This guide describes how to set up your project to consume plugins and how to manage your Gradle library dependencies between your existing Android app and your Flutter module’s plugins.

A. Simple scenario

In the simple cases:

Your Flutter module uses a plugin that has no additional Android Gradle dependency because it only uses Android OS APIs, such as the camera plugin.
Your Flutter module uses a plugin that has an Android Gradle dependency, such as ExoPlayer from the video_player plugin, but your existing Android app didn’t depend on ExoPlayer.

There are no additional steps needed. Your add-to-app module will work the same way as a full-Flutter app. Whether you integrate using Android Studio, Gradle subproject or AARs, transitive Android Gradle libraries are automatically bundled as needed into your outer existing app.

B. Plugins needing project edits

Some plugins require you to make some edits to the Android side of your project.

For example, the integration instructions for the firebase_crashlytics plugin require manual edits to your Android wrapper project’s build.gradle file.

For full-Flutter apps, these edits are done in your Flutter project’s /android/ directory.

In the case of a Flutter module, there are only Dart files in your module project. Perform those Android Gradle file edits on your outer, existing Android app rather than in your Flutter module.

提示 Astute readers might notice that the Flutter module directory also contains an .android and an .ios directory. Those directories are Flutter-tool-generated and are only meant to bootstrap Flutter into generic Android or iOS libraries. They should not be edited or checked-in. This allows Flutter to improve the integration point should there be bugs or updates needed with new versions of Gradle, Android, Android Gradle Plugin, etc.

For advanced users, if more modularity is needed and you must not leak knowledge of your Flutter module’s dependencies into your outer host app, you can rewrap and repackage your Flutter module’s Gradle library inside another native Android Gradle library that depends on the Flutter module’s Gradle library. You can make your Android specific changes such as editing the AndroidManifest.xml, Gradle files or adding more Java files in that wrapper library.

C. Merging libraries

The scenario that requires slightly more attention is if your existing Android application already depends on the same Android library that your Flutter module does (transitively via a plugin).

For instance, your existing app’s Gradle may already have:

…
dependencies {
  …
  implementation 'com.crashlytics.sdk.android:crashlytics:2.10.1'
  …
}
…

And your Flutter module also depends on firebase_crashlytics via pubspec.yaml:

…
dependencies:
  …
  firebase_crashlytics: ^0.1.3
  …
…

This plugin usage transitively adds a Gradle dependency again via firebase_crashlytics v0.1.3’s own Gradle file:

…
dependencies {
  …
  implementation 'com.crashlytics.sdk.android:crashlytics:2.9.9'
  …
}
…

The two com.crashlytics.sdk.android:crashlytics dependencies might not be the same version. In this example, the host app requested v2.10.1 and the Flutter module plugin requested v2.9.9.

By default, Gradle v5 resolves dependency version conflicts by using the newest version of the library.

This is generally ok as long as there are no API or implementation breaking changes between the versions. For example, you might use the new Crashlytics library in your existing app as follows:

…
dependencies {
  …
  implementation 'com.google.firebase:firebase-crashlytics:17.0.0-beta03
  …
}
…

This approach won’t work since there are major API differences between the Crashlytics’ Gradle library version v17.0.0-beta03 and v2.9.9.

For Gradle libraries that follow semantic versioning, you can generally avoid compilation and runtime errors by using the same major semantic version in your existing app and Flutter module plugin.

将 Flutter module 集成到 iOS 项目

系统要求
System requirements
创建 Flutter module
Create a Flutter module
- 模块组织
  Module organization
在你的既有应用中集成 Flutter module
Embed the Flutter module in your existing application
Local Network Privacy Permissions
Apple Silicon (arm64 Macs)
开发
Development

Flutter 可以以 framework 框架的形式添加到你的既有 iOS 应用中。

Flutter can be incrementally added into your existing iOS application as embedded frameworks.

请参阅 add_to_app代码示例的 iOS 目录。

For examples, see the iOS directories in the add_to_app code samples.

系统要求

System requirements

你的开发环境必须满足 Flutter 对 macOS 系统的版本要求并已经安装 Xcode，Flutter 支持 iOS 8.0 及以上。此外，你还需要 1.10 或以上版本的 CocoaPods

Your development environment must meet the macOS system requirements for Flutter with Xcode installed. Flutter supports iOS 9.0 and later. Additionally, you will need CocoaPods version 1.10 or later.

创建 Flutter module

Create a Flutter module

为了将 Flutter 集成到你的既有应用里，第一步要创建一个 Flutter module。

To embed Flutter into your existing application, first create a Flutter module.

在命令行中执行：

From the command line, run:

cd some/path/
flutter create --template module my_flutter

Flutter module 会创建在 some/path/my_flutter/ 目录。在这个目录中，你可以像在其它 Flutter 项目中一样，执行 flutter 命令。比如 flutter run --debug 或者 flutter build ios。同样，你也可以通过 Android Studio/IntelliJ 或者 VS Code 中的 Flutter 和 Dart 插件运行这个模块，在集成到现有应用前，这个项目在 Flutter module 中包含了一个单视图的示例代码，对 Flutter 侧代码的测试会有帮助。

A Flutter module project is created at some/path/my_flutter/. From that directory, you can run the same flutter commands you would in any other Flutter project, like flutter run --debug or flutter build ios. You can also run the module in Android Studio/IntelliJ or VS Code with the Flutter and Dart plugins. This project contains a single-view example version of your module before it’s embedded in your existing application, which is useful for incrementally testing the Flutter-only parts of your code.

模块组织

Module organization

在 my_flutter 模块，目录结构和普通 Flutter 应用类似：

The my_flutter module directory structure is similar to a normal Flutter application:

my_flutter/
├── .ios/
│   ├── Runner.xcworkspace
│   └── Flutter/podhelper.rb
├── lib/
│   └── main.dart
├── test/
└── pubspec.yaml

添加你的 Dart 代码到 lib/ 目录。

Add your Dart code to the lib/ directory.

添加 Flutter 依赖到 my_flutter/pubspec.yaml，包括 Flutter packages 和 plugins。

Add Flutter dependencies to my_flutter/pubspec.yaml, including Flutter packages and plugins.

.ios/ 隐藏文件夹包含了一个 Xcode workspace，用于单独运行你的 Flutter module。它是一个独立启动 Flutter 代码的壳工程，并且包含了一个帮助脚本，用于编译 framewroks 或者使用 CocoaPods 将 Flutter module 集成到你的既有应用。

The .ios/ hidden subfolder contains an Xcode workspace where you can run a standalone version of your module. It is a wrapper project to bootstrap your Flutter code, and contains helper scripts to facilitate building frameworks or embedding the module into your existing application with CocoaPods.

提示

iOS 代码要添加到你的既有应用或者 Flutter plugin中，而不是 Flutter module 的 .ios/ 目录下。 .ios/ 下的改变不会集成到你的既有应用，并且这有可能被 Flutter 重写。

Add custom iOS code to your own existing application’s project or to a plugin, not to the module’s .ios/ directory. Changes made in your module’s .ios/ directory do not appear in your existing iOS project using the module, and may be overwritten by Flutter.

由于 .ios/ 目录是自动生成的，因此请勿对其进行版本控制。在新机器上构建 module 时，请在使用 Flutter module 构建 iOS 项目之前，先于 my_flutter 目录运行 flutter pub get 以生成 .ios/ 目录。

Do not source control the .ios/ directory since it’s autogenerated. Before building the module on a new machine, run flutter pub get in the my_flutter directory first to regenerate the .ios/ directory before building iOS project using the Flutter module.

在你的既有应用中集成 Flutter module

Embed the Flutter module in your existing application

这里有两种方式可以将 Flutter 集成到你的既有应用中。

There are two ways to embed Flutter in your existing application.

使用 CocoaPods 依赖管理和已安装的 Flutter SDK 。（推荐）
Use the CocoaPods dependency manager and installed Flutter SDK. (Recommended.)
把 Flutter engine 、你的 dart 代码和所有 Flutter plugin 编译成 framework 。用 Xcode 手动集成到你的应用中，并更新编译设置。
Create frameworks for the Flutter engine, your compiled Dart code, and all Flutter plugins. Manually embed the frameworks, and update your existing application’s build settings in Xcode.

使用 Flutter 会增加应用体积。

Using Flutter increases your app size.

选项 A - 使用 CocoaPods 和 Flutter SDK 集成

Option A - Embed with CocoaPods and the Flutter SDK

这个方法需要你的项目的所有开发者，都在本地安装 Flutter SDK。只需要在 Xcode 中编译应用，就可以自动运行脚本来集成 dart 代码和 plugin。这个方法允许你使用 Flutter module 中的最新代码快速迭代开发，而无需在 Xcode 以外执行额外的命令。

This method requires every developer working on your project to have a locally installed version of the Flutter SDK. Simply build your application in Xcode to automatically run the script to embed your Dart and plugin code. This allows rapid iteration with the most up-to-date version of your Flutter module without running additional commands outside of Xcode.

下面的示例假设你的既有应用和 Flutter module 在相邻目录。如果你有不同的目录结构，需要适配到对应的路径。

The following example assumes that your existing application and the Flutter module are in sibling directories. If you have a different directory structure, you may need to adjust the relative paths.

some/path/
├── my_flutter/
│   └── .ios/
│       └── Flutter/
│         └── podhelper.rb
└── MyApp/
    └── Podfile

如果你的应用（MyApp）还没有 Podfile，根据 CocoaPods getting started guide 来在项目中添加 Podfile。

If your existing application (MyApp) doesn’t already have a Podfile, follow the CocoaPods getting started guide to add a Podfile to your project.

在 Podfile 中添加下面代码：

Add the following lines to your Podfile:

flutter_application_path = '../my_flutter'
load File.join(flutter_application_path, '.ios', 'Flutter', 'podhelper.rb')

每个需要集成 Flutter 的 Podfile target，执行 install_all_flutter_pods(flutter_application_path)：
For each Podfile target that needs to embed Flutter, call install_all_flutter_pods(flutter_application_path).
```
target 'MyApp' do
  install_all_flutter_pods(flutter_application_path)
end
```
运行 pod install。
Run pod install.

提示

当你在 my_flutter/pubspec.yaml 改变了 Flutter plugin 依赖，需要在 Flutter module 目录运行 flutter pub get，来更新会被podhelper.rb 脚本用到的 plugin 列表，然后再次在你的应用目录 some/path/MyApp 运行 pod install.
When you change the Flutter plugin dependencies in my_flutter/pubspec.yaml, run flutter pub get in your Flutter module directory to refresh the list of plugins read by the podhelper.rb script. Then, run pod install again from your application at some/path/MyApp.

podhelper.rb 脚本会把你的 plugins， Flutter.framework，和 App.framework 集成到你的项目中。

The podhelper.rb script embeds your plugins, Flutter.framework, and App.framework into your project.

你应用的 Debug 和 Release 编译配置，将会集成相对应的 Debug 或 Release 的编译产物。可以增加一个 Profile 编译配置用于在 profile 模式下测试应用。

Your app’s Debug and Release build configurations embed the Debug or Release build modes of Flutter, respectively. Add a Profile build configuration to your app to test in profile mode.

在 Xcode 中打开 MyApp.xcworkspace ，你现在可以使用 ⌘B 编译项目了。

Open MyApp.xcworkspace in Xcode. You can now build the project using ⌘B.

选项 B - 在 Xcode 中集成 frameworks

Option B - Embed frameworks in Xcode

除了上面的方法，你也可以创建必备的 frameworks，手动修改既有 Xcode 项目，将他们集成进去。当你组内其它成员们不能在本地安装 Flutter SDK 和 CocoaPods，或者你不想使用 CocoaPods 作为既有应用的依赖管理时，这种方法会比较合适。但是每当你在 Flutter module 中改变了代码，都必须运行 flutter build ios-framework。

Alternatively, you can generate the necessary frameworks and embed them in your application by manually editing your existing Xcode project. You may do this if members of your team can’t locally install Flutter SDK and CocoaPods, or if you don’t want to use CocoaPods as a dependency manager in your existing applications. You must run flutter build ios-framework every time you make code changes in your Flutter module.

如果你使用前面的使用 CocoaPods 和 Flutter SDK 集成，你可以跳过本步骤。

If you’re using the previous Embed with CocoaPods and Flutter tools method, you can skip these instructions.

下面的示例假设你想在 some/path/MyApp/Flutter/ 目录下创建 frameworks：

The following example assumes that you want to generate the frameworks to some/path/MyApp/Flutter/.

flutter build ios-framework --output=some/path/MyApp/Flutter/

some/path/MyApp/
└── Flutter/
    ├── Debug/
    │   ├── Flutter.xcframework
    │   ├── App.xcframework
    │   ├── FlutterPluginRegistrant.xcframework (only if you have plugins with iOS platform code)
    │   └── example_plugin.xcframework (each plugin is a separate framework)
    ├── Profile/
    │   ├── Flutter.xcframework
    │   ├── App.xcframework
    │   ├── FlutterPluginRegistrant.xcframework
    │   └── example_plugin.xcframework
    └── Release/
        ├── Flutter.xcframework
        ├── App.xcframework
        ├── FlutterPluginRegistrant.xcframework
        └── example_plugin.xcframework

在 Xcode 中将生成的 frameworks 集成到你的既有应用中。例如，你可以在 some/path/MyApp/Flutter/Release/ 目录拖拽 frameworks 到你的应用 target 编译设置的 General > Frameworks, Libraries, and Embedded Content 下，然后在 Embed 下拉列表中选择 “Embed & Sign”。

Embed and link the generated frameworks into your existing application in Xcode. There are multiple ways to do this—use the method that is best for your project.

链接到框架

Link on the frameworks

例如，你可以将框架从 Finder 的 some/path/MyApp/Flutter/Release/ 拖到你的目标项目中，然后点击以下步骤 build settings > Build Phases > Link Binary With Libraries。

For example, you can drag the frameworks from some/path/MyApp/Flutter/Release/ in Finder into your target’s Build Settings > Build Phases > Link Binary With Libraries.

在 target 的编译设置中的 Framework Search Paths (FRAMEWORK_SEARCH_PATHS) 增加 $(PROJECT_DIR)/Flutter/Release/。

In the target’s build settings, add $(PROJECT_DIR)/Flutter/Release/ to the Framework Search Paths (FRAMEWORK_SEARCH_PATHS).

Embed the frameworks

内嵌框架

生成的动态框架必须嵌入你的应用并且在运行时被加载。

The generated dynamic frameworks must be embedded into your app to be loaded at runtime.

例如，你可以从应用框架组中拖拽框架（除了 FlutterPluginRegistrant 以及其他的静态框架）到你的目标 ‘ build settings > Build Phases > Embed Frameworks。然后从下拉菜单中选择 “Embed & Sign”。

For example, you can drag the framework (except for FlutterPluginRegistrant and any other static frameworks) from your application’s Frameworks group into your target’s Build Settings > Build Phases > Embed Frameworks. Then, select Embed & Sign from the drop-down list.

你现在可以在 Xcode中使用 ⌘B 编译项目。

You should now be able to build the project in Xcode using ⌘B.

小提示

如果你想在 Debug 编译配置下使用 Debug 版本的 Flutter frameworks，在 Release 编译配置下使用 Release 版本的 Flutter frameworks，在 MyApp.xcodeproj/project.pbxproj 文件中，尝试在所有 Flutter 相关 frameworks 上使用 path = "Flutter/$(CONFIGURATION)/example.framework"; 替换 path = Flutter/Release/example.framework; （注意添加引号 "）。

To embed the Debug version of the Flutter frameworks in your Debug build configuration and the Release version in your Release configuration, in your MyApp.xcodeproj/project.pbxproj, try replacing path = Flutter/Release/example.xcframework; with path = "Flutter/$(CONFIGURATION)/example.xcframework"; for all added frameworks. (Note the added ".)

你也必须在 Framework Search Paths (FRAMEWORK_SEARCH_PATHS) 编译设置中使用 $(PROJECT_DIR)/Flutter/$(CONFIGURATION)。

You must also add $(PROJECT_DIR)/Flutter/$(CONFIGURATION) to the Framework Search Paths (FRAMEWORK_SEARCH_PATHS) build setting.

选项 C - 使用 CocoaPods 在 Xcode 和 Flutter 框架中内嵌应用和插件框架

Option C - Embed application and plugin frameworks in Xcode and Flutter framework with CocoaPods

除了将一个很大的 Flutter.framework 分发给其他开发者、机器或者持续集成 (CI) 系统之外，你可以加入一个参数 --cocoapods 将 Flutter 框架作为一个 CocoaPods 的 podspec 文件分发。这将会生成一个 Flutter.podspec 文件而不再生成 Flutter.framework 引擎文件。如选项 B 中所说的那样，它将会生成 App.framework 和插件框架。

Alternatively, instead of distributing the large Flutter.xcframework to other developers, machines, or continuous integration systems, you can instead generate Flutter as CocoaPods podspec by adding the flag --cocoapods. This produces a Flutter.podspec instead of an engine Flutter.xcframework. The App.xcframework and plugin frameworks are generated as described in Option B.

flutter build ios-framework --cocoapods --output=some/path/MyApp/Flutter/

some/path/MyApp/
└── Flutter/
    ├── Debug/
    │   ├── Flutter.podspec
    │   ├── App.xcframework
    │   ├── FlutterPluginRegistrant.xcframework
    │   └── example_plugin.xcframework (each plugin with iOS platform code is a separate framework)
    ├── Profile/
    │   ├── Flutter.podspec
    │   ├── App.xcframework
    │   ├── FlutterPluginRegistrant.xcframework
    │   └── example_plugin.xcframework
    └── Release/
        ├── Flutter.podspec
        ├── App.xcframework
        ├── FlutterPluginRegistrant.xcframework
        └── example_plugin.xcframework

Host apps using CocoaPods can add Flutter to their Podfile:

pod 'Flutter', :podspec => 'some/path/MyApp/Flutter/[build mode]/Flutter.podspec'

Embed and link the generated App.xcframework, FlutterPluginRegistrant.xcframework, and any plugin frameworks into your existing application as described in Option B.

Local Network Privacy Permissions

On iOS 14 and higher, enable the Dart multicast DNS service in the Debug version of your app to add debugging functionalities such as hot-reload and DevTools via flutter attach.

One way to do this is to maintain a separate copy of your app’s Info.plist per build configuration. The following instructions assume the default Debug and Release. Adjust the names as needed depending on your app’s build configurations.

Rename your app’s Info.plist to Info-Debug.plist. Make a copy of it called Info-Release.plist and add it to your Xcode project.
In Info-Debug.plist only add the key NSBonjourServices and set the value to an array with the string _dartobservatory._tcp. Note Xcode will display this as “Bonjour services”.

Optionally, add the key NSLocalNetworkUsageDescription set to your desired customized permission dialog text.
In your target’s build settings, change the Info.plist File (INFOPLIST_FILE) setting path from path/to/Info.plist to path/to/Info-$(CONFIGURATION).plist.

This will resolve to the path Info-Debug.plist in Debug and Info-Release.plist in Release.

Alternatively, you can explicitly set the Debug path to Info-Debug.plist and the Release path to Info-Release.plist.
If the Info-Release.plist copy is in your target’s Build Settings > Build Phases > Copy Bundle Resources build phase, remove it.

The first Flutter screen loaded by your Debug app will now prompt for local network permission. The permission can also be allowed by enabling Settings > Privacy > Local Network > Your App.

Apple Silicon (`arm64` Macs)

Flutter 目前暂未支持 arm64 的 iOS 模拟器。要在 Apple Silicon Mac 设备上运行你的宿主应用，请从模拟器支持架构中移除 arm64。

Flutter does not yet support arm64 iOS simulators. To run your host app on an Apple Silicon Mac, exclude arm64 from the simulator architectures.

在宿主应用的 Target 中，找到名为 Excluded Architectures (EXCLUDED_ARCHS) 的构建设置。单击右侧的箭头指示器图标以展开可用的构建配置。将鼠标悬停在 Debug 处并单击加号图标。将 Any SDK 更改为 Any iOS Simulator SDK。然后向构建设置值中添加 arm64。

In your host app target, find the Excluded Architectures (EXCLUDED_ARCHS) build setting. Click the right arrow disclosure indicator icon to expand the available build configurations. Hover over Debug and click the plus icon. Change Any SDK to Any iOS Simulator SDK. Add arm64 to the build settings value.

Set conditional EXCLUDED_ARCHS build setting

当全部都正确设置后，Xcode 将会向你的 project.pbxproj 文件中添加 "EXCLUDED_ARCHS[sdk=iphonesimulator*]" = arm64;。

When done correctly, Xcode will add "EXCLUDED_ARCHS[sdk=iphonesimulator*]" = arm64; to your project.pbxproj file.

然后对全部 iOS 目标再次执行单元测试。

Repeat for any iOS unit test targets.

开发

Development

你现在可以添加一个 Flutter 页面到你的既有应用中。

You can now add a Flutter screen to your existing application.

在 iOS 应用中添加 Flutter 页面

启动 FlutterEngine 和 FlutterViewController
Start a FlutterEngine and FlutterViewController
使用 FlutterAppDelegate
Using the FlutterAppDelegate
启动选项
Launch options

本指南描述了怎样在既有 iOS 应用中添加单个 Flutter 页面。

This guide describes how to add a single Flutter screen to an existing iOS app.

启动 FlutterEngine 和 FlutterViewController

Start a FlutterEngine and FlutterViewController

为了在既有 iOS 应用中展示 Flutter 页面，请启动 FlutterEngine 和 FlutterViewController。

To launch a Flutter screen from an existing iOS, you start a FlutterEngine and a FlutterViewController.

FlutterEngine 的寿命可能与 FlutterViewController 相同，也可能超过 FlutterViewController。

The FlutterEngine may have the same lifespan as your FlutterViewController or outlive your FlutterViewController.

加载顺序和性能里有更多关于预热 engine 的延迟和内存取舍的分析。

See Loading sequence and performance for more analysis on the latency and memory trade-offs of pre-warming an engine.

创建一个 FlutterEngine

Create a FlutterEngine

创建 FlutterEngine 的合适位置取决于您的应用。作为示例，我们将在应用启动的 app delegate 中创建一个 FlutterEngine，并作为属性暴露给外界。

The proper place to create a FlutterEngine is specific to your host app. As an example, we demonstrate creating a FlutterEngine, exposed as a property, on app startup in the app delegate.

Objective-C
Swift

在 AppDelegate.h:

In AppDelegate.h:

@import UIKit;
@import Flutter;

@interface AppDelegate : FlutterAppDelegate // More on the FlutterAppDelegate below.
@property (nonatomic,strong) FlutterEngine *flutterEngine;
@end

在 AppDelegate.m:

In AppDelegate.m:

// Used to connect plugins (only if you have plugins with iOS platform code).
#import <FlutterPluginRegistrant/GeneratedPluginRegistrant.h>

#import "AppDelegate.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey, id> *)launchOptions {
  self.flutterEngine = [[FlutterEngine alloc] initWithName:@"my flutter engine"];
  // Runs the default Dart entrypoint with a default Flutter route.
  [self.flutterEngine run];
  // Used to connect plugins (only if you have plugins with iOS platform code).
  [GeneratedPluginRegistrant registerWithRegistry:self.flutterEngine];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end

在 AppDelegate.swift:

In AppDelegate.swift:

import UIKit
import Flutter
// Used to connect plugins (only if you have plugins with iOS platform code).
import FlutterPluginRegistrant

@UIApplicationMain
class AppDelegate: FlutterAppDelegate { // More on the FlutterAppDelegate.
  lazy var flutterEngine = FlutterEngine(name: "my flutter engine")

  override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Runs the default Dart entrypoint with a default Flutter route.
    flutterEngine.run();
    // Used to connect plugins (only if you have plugins with iOS platform code).
    GeneratedPluginRegistrant.register(with: self.flutterEngine);
    return super.application(application, didFinishLaunchingWithOptions: launchOptions);
  }
}

使用 FlutterEngine 展示 FlutterViewController

Show a FlutterViewController with your FlutterEngine

下面的例子展示了一个普通的 ViewController，包含一个能跳转到 FlutterViewController 的 UIButton，这个 FlutterViewController 使用在 AppDelegate 中创建的 Flutter 引擎 (FlutterEngine)。

The following example shows a generic ViewController with a UIButton hooked to present a FlutterViewController. The FlutterViewController uses the FlutterEngine instance created in the AppDelegate.

Objective-C
Swift

@import Flutter;
#import "AppDelegate.h"
#import "ViewController.h"

@implementation ViewController
- (void)viewDidLoad {
    [super viewDidLoad];

    // Make a button to call the showFlutter function when pressed.
    UIButton *button = [UIButton buttonWithType:UIButtonTypeCustom];
    [button addTarget:self
               action:@selector(showFlutter)
     forControlEvents:UIControlEventTouchUpInside];
    [button setTitle:@"Show Flutter!" forState:UIControlStateNormal];
    button.backgroundColor = UIColor.blueColor;
    button.frame = CGRectMake(80.0, 210.0, 160.0, 40.0);
    [self.view addSubview:button];
}

- (void)showFlutter {
    FlutterEngine *flutterEngine =
        ((AppDelegate *)UIApplication.sharedApplication.delegate).flutterEngine;
    FlutterViewController *flutterViewController =
        [[FlutterViewController alloc] initWithEngine:flutterEngine nibName:nil bundle:nil];
    [self presentViewController:flutterViewController animated:YES completion:nil];
}
@end

import UIKit
import Flutter

class ViewController: UIViewController {
  override func viewDidLoad() {
    super.viewDidLoad()

    // Make a button to call the showFlutter function when pressed.
    let button = UIButton(type:UIButton.ButtonType.custom)
    button.addTarget(self, action: #selector(showFlutter), for: .touchUpInside)
    button.setTitle("Show Flutter!", for: UIControl.State.normal)
    button.frame = CGRect(x: 80.0, y: 210.0, width: 160.0, height: 40.0)
    button.backgroundColor = UIColor.blue
    self.view.addSubview(button)
  }

  @objc func showFlutter() {
    let flutterEngine = (UIApplication.shared.delegate as! AppDelegate).flutterEngine
    let flutterViewController =
        FlutterViewController(engine: flutterEngine, nibName: nil, bundle: nil)
    present(flutterViewController, animated: true, completion: nil)
  }
}

现在，你的 iOS 应用中集成了一个 Flutter 页面。

Now, you have a Flutter screen embedded in your iOS app.

或者 —— 使用隐式 FlutterEngine 创建 FlutterViewController

Alternatively - Create a FlutterViewController with an implicit FlutterEngine

上一个示例还有另一个选择，你可以让 FlutterViewController 隐式创建它自己的 FlutterEngine，而不用提前预热 engine。

As an alternative to the previous example, you can let the FlutterViewController implicitly create its own FlutterEngine without pre-warming one ahead of time.

不过不建议这样做，因为按需创建FlutterEngine 的话，在 FlutterViewController 被 present 出来之后，第一帧图像渲染完之前，将会引入明显的延迟。但是当 Flutter 页面很少被展示时，当对决定何时启动 Dart VM 没有好的启发时，当 Flutter 无需在页面（view controller）之间保持状态时，此方式可能会有用。

This is not usually recommended because creating a FlutterEngine on-demand could introduce a noticeable latency between when the FlutterViewController is presented and when it renders its first frame. This could, however, be useful if the Flutter screen is rarely shown, when there are no good heuristics to determine when the Dart VM should be started, and when Flutter doesn’t need to persist state between view controllers.

为了不使用已经存在的 FlutterEngine 来展现 FlutterViewController，省略 FlutterEngine 的创建步骤，并且在创建 FlutterViewController 时，去掉 engine 的引用。

To let the FlutterViewController present without an existing FlutterEngine, omit the FlutterEngine construction, and create the FlutterViewController without an engine reference.

Objective-C
Swift

// Existing code omitted.
// 省略已经存在的代码
- (void)showFlutter {
  FlutterViewController *flutterViewController =
      [[FlutterViewController alloc] initWithProject:nil nibName:nil bundle:nil];
  [self presentViewController:flutterViewController animated:YES completion:nil];
}
@end

// Existing code omitted.
// 省略已经存在的代码
func showFlutter() {
  let flutterViewController = FlutterViewController(project: nil, nibName: nil, bundle: nil)
  present(flutterViewController, animated: true, completion: nil)
}

查看加载顺序和性能了解更多关于延迟和内存使用的探索。

See Loading sequence and performance for more explorations on latency and memory usage.

使用 FlutterAppDelegate

Using the FlutterAppDelegate

推荐让你应用的 UIApplicationDelegate 继承 FlutterAppDelegate，但不是必须的。

Letting your application’s UIApplicationDelegate subclass FlutterAppDelegate is recommended but not required.

FlutterAppDelegate 有这些功能：

The FlutterAppDelegate performs functions such as:

传递应用的回调，例如 openURL 到 Flutter 的插件 —— local_auth。
Forwarding application callbacks such as openURL to plugins such as local_auth.
传递状态栏点击（这只能在 AppDelegate 中检测）到 Flutter 的点击置顶行为。
Forwarding status bar taps (which can only be detected in the AppDelegate) to Flutter for scroll-to-top behavior.

如果你的 app delegate 不能直接继承 FlutterAppDelegate，让你的 app delegate 实现 FlutterAppLifeCycleProvider 协议，来确保 Flutter plugins 接收到必要的回调。否则，依赖这些事件的 plugins 将会有无法预估的行为。

If your app delegate can’t directly make FlutterAppDelegate a subclass, make your app delegate implement the FlutterAppLifeCycleProvider protocol in order to make sure your plugins receive the necessary callbacks. Otherwise, plugins that depend on these events may have undefined behavior.

例如：

For instance:

@import Flutter;
@import UIKit;
@import FlutterPluginRegistrant;

@interface AppDelegate : UIResponder <UIApplicationDelegate, FlutterAppLifeCycleProvider>
@property (strong, nonatomic) UIWindow *window;
@property (nonatomic,strong) FlutterEngine *flutterEngine;
@end

在具体实现中，应该最大化地委托给 FlutterPluginAppLifeCycleDelegate：

The implementation should delegate mostly to a FlutterPluginAppLifeCycleDelegate:

@interface AppDelegate ()
@property (nonatomic, strong) FlutterPluginAppLifeCycleDelegate* lifeCycleDelegate;
@end

@implementation AppDelegate

- (instancetype)init {
    if (self = [super init]) {
        _lifeCycleDelegate = [[FlutterPluginAppLifeCycleDelegate alloc] init];
    }
    return self;
}

- (BOOL)application:(UIApplication*)application
didFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey, id>*))launchOptions {
    self.flutterEngine = [[FlutterEngine alloc] initWithName:@"io.flutter" project:nil];
    [self.flutterEngine runWithEntrypoint:nil];
    [GeneratedPluginRegistrant registerWithRegistry:self.flutterEngine];
    return [_lifeCycleDelegate application:application didFinishLaunchingWithOptions:launchOptions];
}

// Returns the key window's rootViewController, if it's a FlutterViewController.
// Otherwise, returns nil.
- (FlutterViewController*)rootFlutterViewController {
    UIViewController* viewController = [UIApplication sharedApplication].keyWindow.rootViewController;
    if ([viewController isKindOfClass:[FlutterViewController class]]) {
        return (FlutterViewController*)viewController;
    }
    return nil;
}

- (void)touchesBegan:(NSSet*)touches withEvent:(UIEvent*)event {
    [super touchesBegan:touches withEvent:event];

    // Pass status bar taps to key window Flutter rootViewController.
    if (self.rootFlutterViewController != nil) {
        [self.rootFlutterViewController handleStatusBarTouches:event];
    }
}

- (void)application:(UIApplication*)application
didRegisterUserNotificationSettings:(UIUserNotificationSettings*)notificationSettings {
    [_lifeCycleDelegate application:application
didRegisterUserNotificationSettings:notificationSettings];
}

- (void)application:(UIApplication*)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken {
    [_lifeCycleDelegate application:application
didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

- (void)application:(UIApplication*)application
didReceiveRemoteNotification:(NSDictionary*)userInfo
fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
    [_lifeCycleDelegate application:application
       didReceiveRemoteNotification:userInfo
             fetchCompletionHandler:completionHandler];
}

- (BOOL)application:(UIApplication*)application
            openURL:(NSURL*)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id>*)options {
    return [_lifeCycleDelegate application:application openURL:url options:options];
}

- (BOOL)application:(UIApplication*)application handleOpenURL:(NSURL*)url {
    return [_lifeCycleDelegate application:application handleOpenURL:url];
}

- (BOOL)application:(UIApplication*)application
            openURL:(NSURL*)url
  sourceApplication:(NSString*)sourceApplication
         annotation:(id)annotation {
    return [_lifeCycleDelegate application:application
                                   openURL:url
                         sourceApplication:sourceApplication
                                annotation:annotation];
}

- (void)application:(UIApplication*)application
performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
  completionHandler:(void (^)(BOOL succeeded))completionHandler NS_AVAILABLE_IOS(9_0) {
    [_lifeCycleDelegate application:application
       performActionForShortcutItem:shortcutItem
                  completionHandler:completionHandler];
}

- (void)application:(UIApplication*)application
handleEventsForBackgroundURLSession:(nonnull NSString*)identifier
  completionHandler:(nonnull void (^)(void))completionHandler {
    [_lifeCycleDelegate application:application
handleEventsForBackgroundURLSession:identifier
                  completionHandler:completionHandler];
}

- (void)application:(UIApplication*)application
performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
    [_lifeCycleDelegate application:application performFetchWithCompletionHandler:completionHandler];
}

- (void)addApplicationLifeCycleDelegate:(NSObject<FlutterPlugin>*)delegate {
    [_lifeCycleDelegate addDelegate:delegate];
}
@end

启动选项

Launch options

例子中展示了使用默认启动选项运行 Flutter。

The examples demonstrate running Flutter using the default launch settings.

为了定制化你的 Flutter 运行时，你也可以置顶 Dart 入口、库和路由。

In order to customize your Flutter runtime, you can also specify the Dart entrypoint, library, and route.

Dart 入口

Dart entrypoint

在 FlutterEngine 上调用 run，默认将会调用你的 lib/main.dart 文件里的 main() 函数。

Calling run on a FlutterEngine, by default, runs the main() Dart function of your lib/main.dart file.

你也可以使用另一个入口方法 runWithEntrypoint，并使用 NSString 字符串指定一个不同的 Dart 入口。

You can also run a different entrypoint function by using runWithEntrypoint with an NSString specifying a different Dart function.

提示

使用 main() 以外的 Dart 入口函数，必须使用下面的注解，防止被 tree-shaken 优化掉，而没有编译。

Dart entrypoint functions other than main() must be annotated with the following in order to not be tree-shaken away when compiling:

  @pragma('vm:entry-point')
  void myOtherEntrypoint() { ... };

Dart 库

Dart library

另外，在指定 Dart 函数时，你可以指定特定文件的特定函数。

In addition to specifying a Dart function, you can specify an entrypoint function in a specific file.

下面的例子使用 lib/other_file.dart 文件的 myOtherEntrypoint() 函数取代 lib/main.dart 的 main() 函数：

For instance the following runs myOtherEntrypoint() in lib/other_file.dart instead of main() in lib/main.dart:

Objective-C
Swift

[flutterEngine runWithEntrypoint:@"myOtherEntrypoint" libraryURI:@"other_file.dart"];

flutterEngine.run(withEntrypoint: "myOtherEntrypoint", libraryURI: "other_file.dart")

路由

Route

当构建 engine 时，可以为你的 Flutter WidgetsApp 设置一个初始路由。

An initial route can be set for your Flutter WidgetsApp when constructing the engine.

Objective-C
Swift

FlutterEngine *flutterEngine =
    [[FlutterEngine alloc] initWithName:@"my flutter engine"];
[[flutterEngine navigationChannel] invokeMethod:@"setInitialRoute"
                                      arguments:@"/onboarding"];
[flutterEngine run];

let flutterEngine = FlutterEngine(name: "my flutter engine")
flutterEngine.navigationChannel.invokeMethod("setInitialRoute", arguments:"/onboarding")
flutterEngine.run()

这段代码使用 "/onboarding" 取代 "/"，作为你的 dart:ui 的 window.defaultRouteName

This code sets your dart:ui’s window.defaultRouteName to "/onboarding" instead of "/".

Objective-C
Swift

FlutterViewController* flutterViewController =
      [[FlutterViewController alloc] initWithProject:nil
                                        initialRoute:@"/onboarding"
                                             nibName:nil
                                              bundle:nil];

let flutterViewController = FlutterViewController(
      project: nil, initialRoute: "/onboarding", nibName: nil, bundle: nil)

查看文档：路由和导航了解更多 Flutter 路由的内容。

See Navigation and routing for more about Flutter’s routes.

其它

Other

之前的例子仅仅展示了怎样定制 Flutter 实例初始化的几种方式，通过撰写双端平台代码，你可以在 FlutterViewController 展示 Flutter UI 之前，自由地选择你喜欢的，推入数据和准备 Flutter 环境的方式。 The previous example only illustrates a few ways to customize how a Flutter instance is initiated. Using platform channels, you’re free to push data or prepare your Flutter environment in any way you’d like, before presenting the Flutter UI using a FlutterViewController.

The previous example only illustrates a few ways to customize how a Flutter instance is initiated. Using platform channels, you’re free to push data or prepare your Flutter environment in any way you’d like, before presenting the Flutter UI using a FlutterViewController.

在混合开发模式下进行调试

调试混合开发的模块
Debugging your add-to-app module
- 调试
  Debugging

调试混合开发的模块

Debugging your add-to-app module

当你将 Flutter 模块集成到项目中并使用 Flutter 的平台 APIs 来运行 Flutter 引擎和/或 UI 时，你可以与平时运行 Android 或 iOS 应用程序一样，构建和运行你的应用。

Once you’ve integrated the Flutter module to your project and used Flutter’s platform APIs to run the Flutter engine and/or UI, you can then build and run your Android or iOS app the same way you run normal Android or iOS apps.

但就目前而言，Flutter 需要在 FlutterActivity 或 FlutterViewController 中展示 UI 内容。

However, Flutter is now powering the UI in places where you’re showing a FlutterActivity or FlutterViewController.

调试

Debugging

你可能习惯于在 IDE 中运行 flutter run 或者等效的快捷命令，它会自动启动你喜爱的 Flutter 调试工具。同样的，你也可以使用所有 Flutter 的调试功能，例如热重载、性能调试、DevTools 以及在混合开发的场景中设置断点。

You may be used to having your suite of favorite Flutter debugging tools available to you automatically when running flutter run or an equivalent command from an IDE. But you can also use all your Flutter debugging functionalities such as hot reload, performance overlays, DevTools, and setting breakpoints in add-to-app scenarios.

这些功能由 flutter attach 机制提供。 flutter attach 可以通过不同的路径启动，例如通过 SDK 中的命令行工具、VS Code 或者 IntelliJ/Android Studio。

These functionalities are provided by the flutter attach mechanism. flutter attach can be initiated through different pathways, such as through the SDK’s CLI tools, through VS Code or IntelliJ/Android Studio.

flutter attach 可以在你运行 FlutterEngine 时立即进行连接，并在 FlutterEngine 被释放之前一直保持连接。你可以在启动引擎之前执行 flutter attach，它将等待下一个由引擎持有的 Dart VM 进行连接。

flutter attach can connect as soon as you run your FlutterEngine, and remains attached until your FlutterEngine is disposed. But you can invoke flutter attach before starting your engine. flutter attach waits for the next available Dart VM that is hosted by your engine.

终端

Terminal

在终端执行 flutter attach 或者 flutter attach -d deviceId 来连接你的应用。

Run flutter attach or flutter attach -d deviceId to attach from the terminal.

VS Code

在 VS Code 中的状态栏中选择待调试的设备，然后在命令面板运行 Flutter: Attach to Flutter on Device 命令。

Select the correct device using the status bar in VS Code, then run the Flutter: Attach to Flutter on Device command from the command palette.

或者，在你的 Flutter 模块下创建一个 .vscode/launch.json 文件，使用 Run > Start Debugging 命令或按下 F5。

Alternatively, create a .vscode/launch.json file in your Flutter module project to enable attaching using the Run > Start Debugging command or F5:

{
  name: "Flutter: Attach",
  request: "attach",
  type: "dart",
}

IntelliJ / Android Studio

选择要运行 Flutter 模块的设备，然后点击右边的 flutter attach 按钮。

Select the device on which the Flutter module runs so flutter attach filters for the right start signals.

控制加载顺序，优化性能与内存

加载 Flutter
Loading Flutter
内存和延迟
Memory and latency

本页面描述了展示一个 Flutter UI 的分解步骤。知道了这一点，您可以就何时对 Flutter 引擎进行预热，在哪个阶段可以进行哪些操作，以及这些操作的潜在问题和内存成本做出更好、更明智的决策。

This page describes the breakdown of the steps involved to show a Flutter UI. Knowing this, you can make better, more informed decisions about when to pre-warm the Flutter engine, which operations are possible at which stage, and the latency and memory costs of those operations.

加载 Flutter

Loading Flutter

在展示 Flutter UI 时， Android 与 iOS 应用（用于集成到现有应用的两个受支持的平台），纯 Flutter 应用，以及 add-to-app 的模式，在概念上的加载步骤顺序相似。

Android and iOS apps (the two supported platforms for integrating into existing apps), full Flutter apps, and add-to-app patterns have a similar sequence of conceptual loading steps when displaying the Flutter UI.

查找 Flutter 资源

Finding the Flutter resources

Flutter 的引擎运行时和应用已编译的 Dart 代码都被打包为 Android 和 iOS 上的共享库。加载 Flutter 的第一步是在 .apk、.ipa 或 .app 中查找这些资源（以及其他 Flutter 资源，例如图像和字体，假如适用的话还有 JIT 代码）。

Flutter’s engine runtime and your application’s compiled Dart code are both bundled as shared libraries on Android and iOS. The first step of loading Flutter is to find those resources in your .apk/.ipa/.app (along with other Flutter assets such as images, fonts, and JIT code, if applicable).

当您首次在 Android 和 iOS 上调用 API 构建 FlutterEngine 时，就会发生这种情况。

This happens when you construct a FlutterEngine for the first time on both Android and iOS APIs.

加载 Flutter 库

Loading the Flutter library

找到后，引擎的共享库将在每个进程中加载一次内存。

After it’s found, the engine’s shared libraries are memory loaded once per process.

在 Android 上，当构建 FlutterEngine 时也会发生这种情况，因为 JNI 连接器需要引用 Flutter C++ 库。在 iOS 上，这是在首次运行 FlutterEngine 时发生的，例如运行 runWithEntrypoint:。

On Android, this also happens when the FlutterEngine is constructed because the JNI connectors need to reference the Flutter C++ library. On iOS, this happens when the FlutterEngine is first run, such as by running runWithEntrypoint:.

启动 Dart VM

Starting the Dart VM

Dart 运行时负责管理 Dart 代码的 Dart 内存与异步。在 JIT 模式下，它还负责在运行时将 Dart 源代码编译为机器码。

The Dart runtime is responsible for managing Dart memory and concurrency for your Dart code. In JIT mode, it’s additionally responsible for compiling the Dart source code into machine code during runtime.

在 Android 和 iOS 上，每个应用程序会话都存在一个 Dart 运行时。

A single Dart runtime exists per application session on Android and iOS.

在 Android 上首次构建 FlutterEngine，以及在 iOS 上首次运行 Dart 入口时，将完成一次 Dart VM 启动。

A one-time Dart VM start is done when constructing the FlutterEngine for the first time on Android and when running a Dart entrypoint for the first time on iOS.

此时，您的 Dart 代码的 snapshot 也将从应用程序的文件加载到内存中。

At this point, your Dart code’s snapshot is also loaded into memory from your application’s files.

即使您直接使用 Dart SDK而没 Flutter 引擎，也会这样执行，这是一个通用的过程。

This is a generic process that also occurs if you used the Dart SDK directly, without the Flutter engine.

Dart VM 启动后永远不会关闭。

The Dart VM never shuts down after it’s started.

创建并运行一个 Dart Isolate

Creating and running a Dart Isolate

在初始化 Dart 运行时之后，下一步就是 Flutter 引擎对 Dart 运行时的使用。

After the Dart runtime is initialized, the Flutter engine’s usage of the Dart runtime is the next step.

这是通过在 Dart 运行时中启动 Dart Isolate 来完成的。 isolate 是 Dart 的内存和线程容器。此时在宿主平台上还创建了许多辅助线程来支持 isolate，例如用于解除 GPU 处理的线程和用于图像解码的线程。

This is done by starting a Dart Isolate in the Dart runtime. The isolate is Dart’s container for memory and threads. A number of auxiliary threads on the host platform are also created at this point to support the isolate, such as a thread for offloading GPU handling and another for image decoding.

每个 FlutterEngine 实例都存在一个 isolate，并且同一个 Dart VM 可以承载多个 isolate。

One isolate exists per FlutterEngine instance, and multiple isolates can be hosted by the same Dart VM.

在 Android 上，当您在 FlutterEngine 实例上调用 DartExecutor.executeDartEntrypoint() 时，就会发生这种情况。

On Android, this happens when you call DartExecutor.executeDartEntrypoint() on a FlutterEngine instance.

在 iOS 上，当您对 FlutterEngine 实例调用 runWithEntrypoint:时会发生这种情况。

On iOS, this happens when you call runWithEntrypoint: on a FlutterEngine.

此时，Dart 代码会执行默认的入口点方法 (默认是 main.dart 文件的 main() 方法) ，如果你在 main() 方法中调用 Flutter 的 runApp() 方法，则你的 Flutter 应用或库的 widget 树将会创建并构建。如果你需要阻止某些功能在 Flutter 代码中执行，则需要使用枚举值 AppLifecycleState.detached 表示其不绑定在任何 UI 组件上。

At this point, your Dart code’s selected entrypoint (the main() function of your Dart library’s main.dart file, by default) is executed. If you called the Flutter function runApp() in your main() function, then your Flutter app or your library’s widget tree is also created and built. If you need to prevent certain functionalities from executing in your Flutter code, then the AppLifecycleState.detached enum value indicates that the FlutterEngine isn’t attached to any UI components such as a FlutterViewController on iOS or a FlutterActivity on Android.

将 UI 挂载到 Flutter 引擎

Attaching a UI to the Flutter engine

启动后不久，一个标准的完整的 Flutter 应用程序便会达到此状态。

A standard, full Flutter app moves to reach this state as soon as the app is launched.

在 add-to-app 的场景中，例如通过在 Android 上使用 FlutterActivity.withCachedEngine() 方法构建的 Intent，调用 startActivity() 时，或者，在 iOS 上调用 initWithEngine: nibName: bundle:，展示实例化的 FlutterViewController，都会将 FlutterEngine 挂载到 UI 组件。

In an add-to-app scenario, this happens when you attach a FlutterEngine to a UI component such as by calling startActivity() with an Intent built using FlutterActivity.withCachedEngine() on Android. Or, by presenting a FlutterViewController initialized by using initWithEngine: nibName: bundle: on iOS.

如果在没有启动 Flutter UI 组件的情况下也是如此, 例如在 Android 上使用 FlutterActivity.createDefaultIntent() 或在 iOS 上使用 FlutterViewController initWithProject: nibName: bundle: 预热一个 FlutterEngine。在这些情况下，将创建一个隐式的 FlutterEngine。

This is also the case if a Flutter UI component was launched without pre-warming a FlutterEngine such as with FlutterActivity.createDefaultIntent() on Android, or with FlutterViewController initWithProject: nibName: bundle: on iOS. An implicit FlutterEngine is created in these cases.

在后台，这两个平台的UI组件都为 FlutterEngine 提供了渲染层，例如 Android 上的 Surface 或 iOS 上的 CAEAGLLayer 或 CAMetalLayer。

Behind the scene, both platform’s UI components provide the FlutterEngine with a rendering surface such as a Surface on Android or a CAEAGLLayer or CAMetalLayer on iOS.

此时，您的 Flutter 程序生成的 Layer 树将转换为 OpenGL（或 Vulkan 或 Metal）GPU 指令。

At this point, the Layer tree generated by your Flutter program, per frame, is converted into OpenGL (or Vulkan or Metal) GPU instructions.

内存和延迟

Memory and latency

显示 Flutter UI 会耗费不少时间。提前启动 Flutter 引擎可以降低时间开销。

Showing a Flutter UI has a non-trivial latency cost. This cost can be lessened by starting the Flutter engine ahead of time.

对于 add-to-app 的场景，预热相应的选择是，让您决定什么时候预加载 FlutterEngine （即加载 Flutter 库，启动 Dart VM 并在 isolate 中运行入口点），以及确定内存的占用与时间开销。您还需要知道，在将 UI 组件随后挂载到该 FlutterEngine 时，预热会如何影响 Flutter 渲染首帧的内存和时间开销。

The most relevant choice for add-to-app scenarios is for you to decide when to pre-load a FlutterEngine (that is, to load the Flutter library, start the Dart VM, and run entrypoint in an isolate), and what the memory and latency cost is of that pre-warm. You also need to know how the pre-warm affects the memory and latency cost of rendering a first Flutter frame when the UI component is subsequently attached to that FlutterEngine.

用 Flutter v1.10.3 版本，在 2015 年的低端设备上测试，release AOT 模式下，预热 FlutterEngine 的开销：

As of Flutter v1.10.3, and testing on a low-end 2015 class device in release-AOT mode, pre-warming the FlutterEngine costs:

Android 平台需要 42 MB 内存，耗费 1530 毫秒。主线程阻塞了 330 毫秒；
42 MB and 1530 ms to prewarm on Android. 330 ms of it is a blocking call on the main thread.
iOS 平台需要 22 MB 内存，耗费 860 毫秒。主线程阻塞了 260 毫秒。
22 MB and 860 ms to prewarm on iOS. 260 ms of it is a blocking call on the main thread.

Flutter 用户界面可以在预热期间被加载。所需时间与渲染出首帧的时间有关。

A Flutter UI can be attached during the pre-warm. The remaining time is joined to the time-to-first-frame latency.

在内存方面的开销（具体根据使用情况而定）可能是：

Memory-wise, a cost sample (variable, depending on the use case) could be:

约 4 MB 系统内存用于创建 pthread；
~4 MB OS’s memory usage for creating pthreads.
约 10 MB 是 GPU 驱动内存；
~10 MB GPU driver memory.
约 1 MB 是用于 Dart 运行时管理的内存；
~1 MB for Dart runtime-managed memory.
约 5 MB 用于 Dart 加载的字体映射。
~5 MB for Dart-loaded font maps.

在时间方面的开销（具体根据使用情况而定）可能是：

Latency-wise, a cost sample (variable, depending on the use case) could be:

约 20 毫秒用于从应用包中收集 Flutter 资源；
~20 ms to collect the Flutter assets from the application package.
约 15 毫秒用于 dlopen 加载 Flutter 引擎的库；
~15 ms to dlopen the Flutter engine library.
约 200 毫秒用于创建 Dart VM 并加载 AOT snapshot；
~200 ms to create the Dart VM and load the AOT snapshot.
约 200 毫秒用于加载 Flutter 依赖的字体和资源；
~200 ms to load Flutter-dependent fonts and assets.
约 400 毫秒来运行应用入口，创建第一个 widget 树，并编译所需的 GPU 着色器程序。
~400 ms to run the entrypoint, create the first widget tree, and compile the needed GPU shader programs.

应该对 FlutterEngine 进行预热，不应过于提早，以延迟内存占用，但又要避免 Flutter 引擎初始化的时机与显示 Flutter 的首帧的时机赶在一起。

The FlutterEngine should be pre-warmed late enough to delay the memory consumption needed but early enough to avoid combining the Flutter engine start-up time with the first frame latency of showing Flutter.

确切的时间取决于应用的结构与不断试探的结果。一个示例是在 Flutter 绘制屏幕之前将 Flutter 引擎加载到屏幕中。

The exact timing depends on the app’s structure and heuristics. An example would be to load the Flutter engine in the screen before the screen is drawn by Flutter.

引擎预热后，加载 UI 首帧的成本为：

Given an engine pre-warm, the first frame cost on UI attach is:

在 Android 上为 320 毫秒，另外需要 12 MB 的内存（在很大程度上取决于屏幕的物理像素大小）；
320 ms on Android and an additional 12 MB (highly dependent on the screen’s physical pixel size).
在 iOS 上为 200 毫秒，另外需要 16 MB 的内存（在很大程度上取决于屏幕的物理像素大小）。
200 ms on iOS and an additional 16 MB (highly dependent on the screen’s physical pixel size).

在内存方面，开销主要用于渲染的图形内存缓冲区，并且取决于屏幕大小。

Memory-wise, the cost is primarily the graphical memory buffer used for rendering and is dependent on the screen size.

在时间方面，开销主要是在等待系统回调，为 Flutter 提供渲染层，并编译其余无法预先预测的着色器程序。这是一次性的开销。

Latency-wise, the cost is primarily waiting for the OS callback to provide Flutter with a rendering surface and compiling the remaining shader programs that are not pre-emptively predictable. This is a one-time cost.

释放 Flutter UI 组件后，将释放与 UI 相关的内存。这不会影响 Flutter 状态（除非也释放了 FlutterEngine），状态位于 FlutterEngine 中。

When the Flutter UI component is released, the UI-related memory is freed. This doesn’t affect the Flutter state, which lives in the FlutterEngine (unless the FlutterEngine is also released).

关于创建多个 FlutterEngine 对性能影响的详细情况，请参考文档：多个 Flutter 实例。

For performance details on creating more than one FlutterEngine, see multiple Flutters.

多个 Flutter 页面或视图

实验性
Experimental
使用场景
Scenarios
组件
Components
示例
Samples

实验性

Experimental

目前在 Android 和 iOS 上，除了第一个 Flutter 实例以外，其他每一个实例的内存占用量大约为 180kB。

The current memory footprint for each additional Flutter instance beyond the first instance is ~180kB on Android and iOS.

随着 Flutter 2.0.0 正式版的发布，Flutter 实例之间将通过宿主平台的平台通道（或 Pigeon）进行处理。若您对我们平台通信的里程碑感兴趣，或是有其他多个 Flutter 实例的问题，请查看 Issue 72009。

As of the 2.0.0 release, communication between Flutter instances is handled using platform channels (or Pigeon) through the host platform. To see our roadmap on communication, or other multiple-Flutters issues, see Issue 72009.

使用场景

Scenarios

在 Flutter 2.0.0 发布之前，FlutterEngine 的多个实例和相关的 UI 可以同时启动，但是每个实例都有明显的延迟和固定的内存占用。

Before Flutter 2.0.0, multiple instances of FlutterEngine and its associated UI could be launched, but each instance came with significant latency and fixed memory cost.

多个 Flutter 实例在以下场景有优势：

Multiple Flutter instances can be useful in the following scenarios:

集成了 Flutter 界面的应用，其位置并不在路由栈的叶子节点上，且其可能是混合路由栈，即 native -> Flutter -> native -> Flutter。
An application where the integrated Flutter screen is not a leaf node of the navigation graph, and the navigation stack might be a hybrid mixture of native -> Flutter -> native -> Flutter.
多个 Flutter view 同时集成在同一个页面上，且同时显示。
A screen where multiple partial screen Flutter views might be integrated and visible at once.

使用多个 Flutter 实例的优势在于，每一个实例互相独立，各自维护路由栈、UI 和应用状态。这简化了应用程序整体的状态保持考虑，并且进一步模块化。了解更多关于多个 Flutter 使用的动机和场景，请查看 flutter.cn/go/multiple-flutters。

The advantage of using multiple Flutter instances is that each instance is independent and maintains its own internal navigation stack, UI, and application states. This simplifies the overall application code’s responsibility for state keeping and improves modularity. More details on the scenarios motivating the usage of multiple Flutters can be found at docs.flutter.dev/go/multiple-flutters.

Flutter 2.0.0 大幅减少了额外的 Flutter 引擎的内存占用，从 Android 上 约 19MB，iOS 上 约 13MB，降至 约 180kB。将固定成本减少了约 99% 后，您可以更自由地将多个 Flutter 集成至您的应用。

The 2.0.0 Flutter release drastically reduces the memory footprint of additional Flutter engines from ~19MB on Android and ~13MB on iOS, to ~180kB on Android and iOS. This ~99% fixed cost reduction allows the multiple Flutters pattern to be used more liberally in your add-to-app integration.

组件

Components

在 Android 和 iOS 上添加多个 Flutter 实例的主要 API 是基于新的 FlutterEngineGroup 类 (Android API, iOS API) 来创建 FlutterEngine 的，而不是通过以前的 FlutterEngine 构造。

The primary API for adding multiple Flutter instances on both Android and iOS is based on a new FlutterEngineGroup class (Android API, iOS API) to construct FlutterEngines, rather than the FlutterEngine constructors used previously.

尽管 FlutterEngine API 的用法简洁明了，但从 FlutterEngineGroup 生成的 FlutterEngine 具有常用共享资源（例如 GPU 上下文、字体度量和隔离线程的快照）的性能优势，从而加快首次渲染的速度、降低延迟并降低内存占用。

Whereas the FlutterEngine API was direct and easier to consume, the FlutterEngine spawned from the same FlutterEngineGroup have the performance advantage of sharing many of the common, reusable resources such as the GPU context, font metrics, and isolate group snapshot, leading to a faster initial rendering latency and lower memory footprint.

由 FlutterEngineGroup 生成的 FlutterEngine 可以用来关联 UI 相关的类，例如 FlutterActivity 或 FlutterViewController，与通常构造缓存的 FlutterEngine 类似。
FlutterEngines spawned from FlutterEngineGroup can be used to connect to UI classes like FlutterActivity or FlutterViewController in the same way as normally constructed cached FlutterEngines.
第一个 FlutterEngineGroup 生成的 FlutterEngine 不需要持续保活，只要有 1 个可用的 FlutterEngine，就可以随时在各个 FlutterEngine 之间共享资源。
The first FlutterEngine spawned from the FlutterEngineGroup doesn’t need to continue surviving in order for subsequent FlutterEngines to share resources as long as there’s at least 1 living FlutterEngine at all times.
通过 FlutterEngineGroup 生成的首个 FlutterEngine 与使用先前的构造方法构造的 FlutterEngine 有相同的性能特征。
Creating the very first FlutterEngine from a FlutterEngineGroup has the same performance characteristics as constructing a FlutterEngine using the constructors did previously.
当所有由 FlutterEngineGroup 构造的 FlutterEngine 都被销毁后，下一个创建的 FlutterEngine 与首个创造的性能特征相同。
When all FlutterEngines from a FlutterEngineGroup are destroyed, the next FlutterEngine created has the same performance characteristics as the very first engine.
FlutterEngineGroup 本身不需要持续保活。将其销毁后，已生成的 FlutterEngine 不受影响，但无法继续在现有共享的基础上创建新引擎。
The FlutterEngineGroup itself doesn’t need to live beyond all of the spawned engines. Destroying the FlutterEngineGroup doesn’t affect existing spawned FlutterEngines but does remove the ability to spawn additional FlutterEngines that share resources with existing spawned engines.

示例

Samples

您可以在 GitHub 仓库上找到在 Android 和 iOS 上使用 FlutterEngineGroup 的示例。

You can find a sample demonstrating how to use FlutterEngineGroup on both Android and iOS on GitHub.

A sample demonstrating multiple-Flutters

在 Android Studio 或 IntelliJ 里开发 Flutter 应用

安装和设置
Installation and setup
- 更新插件
  Updating the plugins
创建项目
Creating projects
- 创建新项目
  Creating a new project
- 从现有源码创建新项目
  Creating a new project from existing source code
编辑代码，和查看问题
Editing code and viewing issues
运行和调试
Running and debugging
快速编辑和查看效果
Fast edit and refresh development cycle
- 显示性能数据
  Show performance data
Flutter 代码编辑提示
Editing tips for Flutter code
在 Android Studio 中编辑 Android 代码，并获得完整 IDE 支持
Editing Android code in Android Studio with full IDE support
在 IntelliJ IDEA 中编辑 Android 代码
Editing Android code in IntelliJ IDEA
提示和技巧
Tips and tricks
故障排除
Troubleshooting
- 已知问题和反馈
  Known issues and feedback

Android Studio and IntelliJ
Visual Studio Code

安装和设置

Installation and setup

按照编辑工具设定，安装 Dart 和 Flutter 插件。

Follow the Set up an editor instructions to install the Dart and Flutter plugins.

更新插件

Updating the plugins

插件的更新会定期发布，当有更新可用时，你会在 IDE 中收到提示。

Updates to the plugins are shipped on a regular basis. You should be prompted in the IDE when an update is available.

手动检查更新：

To check for updates manually:

打开设置（在 macOS 中点击 Android Studio > Check for Updates，在 Linux 中点击 Help > Check for Updates）。
Open preferences (Android Studio > Check for Updates on macOS, Help > Check for Updates on Linux).
如果存在 dart 或 flutter，更新他们。
If dart or flutter are listed, update them.

创建项目

Creating projects

你可以通过多种方式来创建新项目。

You can create a new project in one of several ways.

创建新项目

Creating a new project

使用 Futter 应用模板创建新的 Flutter 项目：

To create a new Flutter project from the Flutter starter app template:

在 IDE 中，点击 Welcome 窗口，或者主窗口 File > New > Project 中的 New Project。
In the IDE, click New Project from the Welcome window or File > New > Project from the main IDE window.
在菜单中选择 Flutter SDK path，点击 Next。
Specify the Flutter SDK path and click Next.
输入你的 Project name、Description 和 Project location。
Enter your desired Project name, Description and Project location.
如果打算发布此应用，需要设置公司域名。
If you might publish this app, set the company domain.
点击 Finish。
Click Finish.

设置公司域名

Setting the company domain

在创建新应用时，一些 Flutter IDE 插件需要一个逆序的域名，比如 com.example。除了程序名外，在应用发布后，它将作为 Android 应用的包名，以及 iOS 应用的 Bundle ID。如果你可能发布此应用，最好现在就指定好它，应用发布后将无法更改。你的域名应该是唯一的。

When creating a new app, some Flutter IDE plugins ask for an organization name in reverse domain order, something like com.example. Along with the name of the app, this is used as the package name for Android, and the Bundle ID for iOS when the app is released. If you think you might ever release this app, it is better to specify these now. They cannot be changed once the app is released. Your organization name should be unique.

从现有源码创建新项目

Creating a new project from existing source code

创建包含现有 Flutter 源码的新 Flutter 项目：

To create a new Flutter project containing existing Flutter source code files:

在 IDE 中，点击 Welcome 窗口，或者主窗口 File > New > Project 中的 Create New Project。
In the IDE, click Create New Project from the Welcome window or File > New > Project from the main IDE window.

重点提醒

对于 Flutter 项目，请不要使用 New > Project from existing sources。
Do not use the New > Project from existing sources option for Flutter projects.
在菜单中选择 Flutter，点击 Next。
Select Flutter in the menu, and click Next.
在 Project location 下，输入或选择现有 Flutter 源码的文件目录。
Under Project location enter, or browse to, the directory holding your existing Flutter source code files.
点击 Finish。
Click Finish.

编辑代码，和查看问题

Editing code and viewing issues

Dart 插件的代码分析，可以做到：

The Flutter plugin performs code analysis that enables the following:

语法高亮显示。
Syntax highlighting.
基于多种类型分析的代码补全。
Code completions based on rich type analysis.
定位到类型的声明（Navigate > Declaration），查找类型的引用（Edit > Find > Find Usages）。
Navigating to type declarations (Navigate > Declaration), and finding type usages (Edit > Find > Find Usages).
查看当前存在的代码问题（View > Tool Windows > Dart Analysis），所有问题会在 Dart Analysis 窗口中显示

Viewing all current source code problems (View > Tool Windows > Dart Analysis). Any analysis issues are shown in the Dart Analysis pane:

运行和调试

Running and debugging

提示

你可以通过如下方式调试你的应用：

You can debug your app in a few ways.

使用开发者工具 (DevTools), 运行在浏览器里的一系列调试和分析工具， 也包括 Flutter inspector，开发者工具替代了之前的 Observatory 分析工具。
Using DevTools, a suite of debugging and profiling tools that run in a browser and include the Flutter inspector. DevTools replaces the previous browser-based profiling tool, Observatory.
使用 Android Studio（或者 IntelliJ）内置的调试功能，比如设置断点等。
Using Android Studio’s (or IntelliJ’s) built-in debugging features, such as the ability to set breakpoints.
使用 Flutter inspector, 在 Android Studio 和 IntelliJ 内置。
Using the Flutter inspector, directly available in Android Studio and IntelliJ.

下面的介绍文章适用于 Android Studio 和 IntelliJ，更多关于开发者工具的信息，请参看文档：在 Android Studio 上安装和运行开发者工具。

The instructions below describe features available in Android Studio and IntelliJ. For information on launching DevTools, see Running DevTools from Android Studio in the DevTools docs.

在主工具栏，可以运行和调试代码：

Running and debugging are controlled from the main toolbar:

Main IntelliJ toolbar

选择目标设备

Selecting a target

在 IDE 中打开 Flutter 项目时，你会在工具栏的右侧看到一组 Flutter 的特定按钮。

When a Flutter project is open in the IDE, you should see a set of Flutter-specific buttons on the right-hand side of the toolbar.

找到选择目标下拉按钮，点击它会显示出可用设备列表。
Locate the Flutter Target Selector drop-down button. This shows a list of available targets.
选择你希望启动应用的设备。当连接设备或启动模拟器时，列表中将会加入新选项。
Select the target you want your app to be started on. When you connect devices, or start simulators, additional entries appear.

不使用断点运行应用

Run app without breakpoints

点击工具栏中的 Play 按钮，或选择 Run > Run。底部的 Run 窗口会有日志输出：
Click the Play icon in the toolbar, or invoke Run > Run. The bottom Run pane shows logs output.

使用断点运行应用

Run app with breakpoints

如果需要，在源代码中设置断点。
If desired, set breakpoints in your source code.
点击工具栏中的 Debug 按钮，或选择 Run > Debug。
Click the Debug icon in the toolbar, or invoke Run > Debug.
- 底部的 Debugger 窗口会显示出堆栈和变量信息。
  The bottom Debugger pane shows Stack Frames and Variables.
- 底部的 Console 窗口会显示详细的日志输出。
  The bottom Console pane shows detailed logs output.
- 调试基于默认的启动配置，如果需要自定义，点击选择目标下拉按钮，选择 Edit configuration 进行配置。
  Debugging is based on a default launch configuration. To customize this, click the drop-down button to the right of the device selector, and select Edit configuration.

快速编辑和查看效果

Fast edit and refresh development cycle

Flutter 有效加快开发周期。使用 热重载 功能，你可以在修改源码后，几乎马上看到效果。详细信息请查阅使用热重载。

Flutter offers a best-in-class developer cycle enabling you to see the effect of your changes almost instantly with the Stateful Hot Reload feature. See Hot reload for details.

显示性能数据

Show performance data

在 Debug 模式下启动应用后，使用 View > Tool Windows > Flutter Performance 打开性能工具窗口，以查看性能数据以及 widget 的 rebuild 信息。

To view the performance data, including the widget rebuild information, start the app in Debug mode, and then open the Performance tool window using View > Tool Windows > Flutter Performance.

点击 Performance 窗口中的 Show widget rebuild information，查看正在重载的 widget 统计信息和重载频率。右边第二列显示了所在框架的重载次数。如果重载次数过多，会显示一个黄色旋转圆圈。最右一列显示了进入当前页面后 widget 的重载次数。对于未重载的小部件，将显示一个灰色圆圈，否则将显示一个灰色旋转圆圈。

To see the stats about which widgets are being rebuilt, and how often, click Show widget rebuild information in the Performance pane. The exact count of the rebuilds for this frame displays in the second column from the right. For a high number of rebuilds, a yellow spinning circle displays. The column to the far right shows how many times a widget was rebuilt since entering the current screen. For widgets that aren’t rebuilt, a solid grey circle displays. Otherwise, a grey spinning circle displays.

该功能的目的是让你了解 widget 是何时重载的，只看代码的话可能不好发现。如果 widget 在你预想不到的情况下发生了重载，说明你可能需要重构代码，将大型的构建方法拆分成多个 widget。

The purpose of this feature is to make you aware when widgets are rebuilding—you might not realize that this is happening when just looking at the code. If widgets are rebuilding that you didn’t expect, it’s probably a sign that you should refactor your code by splitting up large build methods into multiple widgets.

该工具可以帮助你调试至少四个常见的性能问题：

This tool can help you debug at least four common performance issues:

整个屏幕（或大部分屏幕）由一个 StatefulWidget 构成，导致不必要的 UI 构建。可将 UI 拆分成多个具有较轻量 build() 方法的 widget。
The whole screen (or large pieces of it) are built by a single StatefulWidget, causing unnecessary UI building. Split up the UI into smaller widgets with smaller build() functions.
未在屏幕上显示的 widget 发生了重载。例如，一个延伸到屏幕外的 ListView，或者未给延伸到屏幕外的列表设置 RepaintBoundary，会导致重绘整个列表。
Offscreen widgets are being rebuilt. This can happen, for example, when a ListView is nested in a tall Column that extends offscreen. Or when the RepaintBoundary is not set for a list that extends offscreen, causing the whole list to be redrawn.
AnimatedBuilder 的 build() 方法绘制了一个不需要动画的子树，导致不必要的静态对象重载。
The build() function for an AnimatedBuilder draws a subtree that does not need to be animated, causing unnecessary rebuilds of static objects.
一个 Opacity widget 在 widget tree 中使用了一个不必要的高度，或者通过直接操作 Opacity widget 的透明属性创建 Opacity 动画，导致 widget 和它的子树重载。
An Opacity widget is placed unnecessarily high in the widget tree. Or, an Opacity animation is created by directly manipulating the opacity property of the Opacity widget, causing the widget itself and its subtree to rebuild.

你可以点击表格中的一行，定位到创建指定 widget 的源码位置。随着代码的运行，旋转图标也会在代码窗口中显示，以帮助你观察正在进行的重载。

You can click on a line in the table to navigate to the line in the source where the widget is created. As the code runs, the spinning icons also display in the code pane to help you visualize which rebuilds are happening.

大量的重载并不一定表示存在问题。通常情况下，只有当你通过分析发现性能不理想时，才需要考虑过度重载的问题。

Note that numerous rebuilds doesn’t necessarily indicate a problem. Typically you should only worry about excessive rebuilds if you have already run the app in profile mode and verified that the performance is not what you want.

记住，widget 的重载信息只在 debug 版本中可用，在真机上使用分析构建 (profile build) 进行应用性能分析，使用调试构建 (debug build) 进行性能问题调试。

And remember, the widget rebuild information is only available in a debug build. Test the app’s performance on a real device in a profile build, but debug performance issues in a debug build.

Flutter 代码编辑提示

Editing tips for Flutter code

如果你有其他我们应该提供的代码提示建议，请告诉我们!

If you have additional tips we should share, let us know!

代码辅助和快速修复

Assists & quick fixes

代码辅助功能是特定代码标识符相关的代码修改。当光标放在 Flutter widget 上时，黄色灯泡图标会指示可用的修改，可以通过点击灯泡进行修改，或使用键盘快捷键（在 Linux 和 Windows 上使用 Alt+Enter，在 macOS 上使用 Option+Return），如下图所示：

Assists are code changes related to a certain code identifier. A number of these are available when the cursor is placed on a Flutter widget identifier, as indicated by the yellow lightbulb icon. The assist can be invoked by clicking the lightbulb, or by using the keyboard shortcut (Alt+Enter on Linux and Windows, Option+Return on macOS), as illustrated here:

IntelliJ editing assists

Quick Fixes 快速修复功能也是类似的，当一段代码存在错误时，它会出现并帮助纠正错误。它使用红色灯泡表示。

Quick Fixes are similar, only they are shown with a piece of code has an error and they can assist in correcting it. They are indicated with a red lightbulb.

Wrap with new widget assist

当你有一个 widget 需要嵌套在其他 widget 时，可以使用该功能。例如，需要将 widget 嵌套在 Row 或 Column 中。

This can be used when you have a widget that you want to wrap in a surrounding widget, for example if you want to wrap a widget in a Row or Column.

Wrap widget list with new widget assist

和上面的辅助类似，但它嵌套的是一个 widget 的列表，而不是单个的 widget。

Similar to the assist above, but for wrapping an existing list of widgets rather than an individual widget.

child 和 children 转换辅助

Convert child to children assist

将 child 转换成 children，并且把参数值写进一个 list。

Changes a child argument to a children argument, and wraps the argument value in a list.

实时模板

Live templates

实时模板用于增加典型代码结构的输入速度。输入前缀后，在代码完成窗口中选择它：

Live templates can be used to speed up entering typical code structures. They are invoked by typing their prefix, and then selecting it in the code completion window:

IntelliJ live templates

Flutter 插件包含了以下模板：

The Flutter plugin includes the following templates:

前缀 stless：创建一个 StatelessWidget 的子类。
Prefix stless: Create a new subclass of StatelessWidget.
前缀 stful：创建一个 StatefulWidget 的子类，并关联 State 子类。
Prefix stful: Create a new subclass of StatefulWidget and its associated State subclass.
前缀 stanim：创建一个 StatefulWidget 的子类，并关联 State 子类，包含一个 AnimationController 的初始化字段。
Prefix stanim: Create a new subclass of StatefulWidget and its associated State subclass, including a field initialized with an AnimationController.

你还可以通过 Settings > Editor > Live Templates 定义自定义模板。

You can also define custom templates in Settings > Editor > Live Templates.

键盘快捷键

Keyboard shortcuts

热重载

Hot reload

在 Linux（映射方案默认为 XWin）和 Windows 上，快捷键是 Control+Alt+; 和 Control+Backslash。

On Linux (keymap Default for XWin) and Windows the keyboard shortcuts are Control+Alt+; and Control+Backslash.

在 macOS 上（映射方案 Mac OS X 10.5+）上，快捷键是 Command+Option 和 Command+Backslash。

On macOS (keymap Mac OS X 10.5+ copy) the keyboard shortcuts are Command+Option and Command+Backslash.

可以在 IDE 的设置中修改快捷键：选择 Keymap 后，在右上角的搜索框输入 flutter。右键点击你想修改的快捷键，点击 Add Keyboard Shortcut

Keyboard mappings can be changed in the IDE Preferences/Settings: Select Keymap, then enter flutter into the search box in the upper right corner. Right click the binding you want to change and Add Keyboard Shortcut.

IntelliJ settings keymap

热重载和热重启

Hot reload vs. hot restart

热重载的工作原理是将更新后的代码注入 Dart VM（虚拟机）。不仅包括添加新类，还包括添加方法和字段到已有的类中。但有些类型的代码是无法被热重载的：

Hot reload works by injecting updated source code files into the running Dart VM (Virtual Machine). This includes not only adding new classes, but also adding methods and fields to existing classes, and changing existing functions. A few types of code changes cannot be hot reloaded though:

全部变量的初始化
Global variable initializers
静态变量的初始化
Static field initializers
应用的 main() 方法
The main() method of the app

对于这些更改，你无需结束调试过程而直接热重启 (hot restart) 你的应用：不要点击 Stop 按钮，只需点击 Run 按钮（在运行中），或 Debug 按钮（在调试中），或者按住 Shift 键点击热重载按钮。

For these changes you can fully restart your application, without having to end your debugging session. To perform a hot restart, don’t click the Stop button, simply re-click the Run button (if in a run session) or Debug button (if in a debug session), or shift-click the ‘hot reload’ button.

在 Android Studio 中编辑 Android 代码，并获得完整 IDE 支持

Editing Android code in Android Studio with full IDE support

打开 Flutter 项目的根目录，并不会在 IDE 中显示所有的 Android 文件。 Flutter 应用包含了一个名为 android 的子目录，如果你在 Android Studio 中将该目录作为单独的项目打开，则 IDE 将可以完全支持编辑和重构所有的 Android 文件（比如 Gradle 脚本文件）。

Opening the root directory of a Flutter project doesn’t expose all the Android files to the IDE. Flutter apps contain a subdirectory named android. If you open this subdirectory as its own separate project in Android Studio, the IDE will be able to fully support editing and refactoring all Android files (like Gradle scripts).

如果你已经在 Android Studio 中将整个项目作为 Flutter 应用打开，则有两种方法可以打开 Android 文件，在 IDE 中进行编辑。在进行操作之前，请确保你使用的是最新版本的 Android Studio 和 Flutter 插件。

If you already have the entire project opened as a Flutter app in Android Studio, there are two equivalent ways to open the Android files on their own for editing in the IDE. Before trying this, make sure that you’re on the latest version of Android Studio and the Flutter plugins.

在“项目视图 (project view)”中，你可以在 flutter 应用的根目录下看到一个 android 的子目录。右键点击它，选择 Flutter > Open Android module in Android Studio。
In the “project view”, you should see a subdirectory immediately under the root of your flutter app named android. Right click on it, then select Flutter > Open Android module in Android Studio.
或者，你也可以打开 android 目录下的任意文件进行编辑。你会在编辑器的顶部看到一个 “Flutter commands” 的横幅，包含一个 Open for Editing in Android Studio 的标签，点击它。
OR, you can open any of the files under the android subdirectory for editing. You should then see a “Flutter commands” banner at the top of the editor with a link labeled Open for Editing in Android Studio. Click that link.

这两种方法，Android Studio 都允许你选择使用单独的窗口，或替换现有窗口打开新项目，两种都是可以的。

For both options, Android Studio gives you the option to use separate windows or to replace the existing window with the new project when opening a second project. Either option is fine.

如果你还没在 Android Studio 中打开 Flutter 项目，你可以一开始就将 Android 文件作为项目打开：

If you don’t already have the Flutter project opened in Android studio, you can open the Android files as their own project from the start:

点击欢迎窗口中的 Open an existing Android Studio Project。如果 Android Studio 已打开，也可以点击 File > Open。
Click Open an existing Android Studio Project on the Welcome splash screen, or File > Open if Android Studio is already open.
打开 flutter 应用根目录下的 android 子目录。例如，项目名为 flutter_app，则打开 flutter_app/android。
Open the android subdirectory immediately under the flutter app root. For example if the project is called flutter_app, open flutter_app/android.

如果你还未运行过你的 Flutter 应用，可能会在打开 android 项目时，看到 Android Studio 构建失败的报告。运行项目根目录的 flutter pub get，并通过点击 Build > Make 重建项目，可修复该问题。

If you haven’t run your Flutter app yet, you might see Android Studio report a build error when you open the android project. Run flutter pub get in the app’s root directory and rebuild the project by selecting Build > Make to fix it.

在 IntelliJ IDEA 中编辑 Android 代码

Editing Android code in IntelliJ IDEA

要在 IntelliJ IDEA 中编辑 Android 代码，你需要配置 Android SDK 的位置：

To enable editing of Android code in IntelliJ IDEA, you need to configure the location of the Android SDK:

在 Preferences > Plugins 中，启用 Android Support。
In Preferences > Plugins, enable Android Support if you haven’t already.
在项目视图中，右键点击 android 文件夹，然后选择 Open Module Settings。
Right-click the android folder in the Project view, and select Open Module Settings.
在 Sources 选项中，找到 Language level，并选择 level 8 或更高级别。
In the Sources tab, locate the Language level field, and select level 8 or later.
在 Dependencies 选项中，找到 Module SDK，并选择一个 Android SDK。如果这里没有列出 SDK，点击 New 并指定 Android SDK 的位置。确保选择和 Flutter 使用相匹配的 Android SDK（如 flutter doctor 中所示）。
In the Dependencies tab, locate the Module SDK field, and select an Android SDK. If no SDK is listed, click New and specify the location of the Android SDK. Make sure to select an Android SDK matching the one used by Flutter (as reported by flutter doctor).
点击 OK。
Click OK.

提示和技巧

Tips and tricks

故障排除

Troubleshooting

已知问题和反馈

Known issues and feedback

Flutter 插件 README 文件中记录了可能影响你使用体验的已知重要问题。

Important known issues that might impact your experience are documented in the Flutter plugin README file.

所有已知问题都会在问题跟踪器中进行跟踪：

All known bugs are tracked in the issue trackers:

Flutter 插件： GitHub 问题跟踪
Flutter plugin: GitHub issue tracker
Dart 插件: JetBrains 问题跟踪
Dart plugin: JetBrains YouTrack

我们欢迎所有的错误、问题以及功能反馈。在提交新问题前：

We welcome feedback, both on bugs/issues and feature requests. Prior to filing new issues:

在问题跟踪器总快速搜索查看问题是否已存在。
Do a quick search in the issue trackers to see if the issue is already tracked.
确保你已经更新最新版本的插件。
Make sure you have updated to the most recent version of the plugin.

当你在提交新的 issue 时，确保带上运行了 flutter doctor 命令之后的返回内容。

When filing new issues, include the output of flutter doctor.

在 VS Code 里开发 Flutter 应用

安装和配置
Installation and setup
- 更新扩展程序
  Updating the extension
创建项目
Creating projects
- 新建项目
  Creating a new project
- 从现有源代码打开项目
  Opening a project from existing source code
编写代码及查看问题
Editing code and viewing issues
运行和调试
Running and debugging
快速编辑和刷新开发周期
Fast edit and refresh development cycle
进阶调试
Advanced debugging
- 可视化布局问题调试
  Debugging visual layout issues
- 调试外部库
  Debugging external libraries
Flutter 代码编辑提示
Editing tips for Flutter code
故障排除
Troubleshooting
- 已知问题和反馈
  Known issues and feedback

安装和配置

Installation and setup

根据编辑工具设定的指引来安装 Dart 和 Flutter 扩展（也叫做插件）。

Follow the Set up an editor instructions to install the Dart and Flutter extensions (also called plugins).

更新扩展程序

Updating the extension

扩展的更新会定期发布。默认情况下，当有可用的更新时 VS Code 会自动更新扩展。

Updates to the extensions are shipped on a regular basis. By default, VS Code automatically updates extensions when updates are available.

手动安装更新：

To install updates manually:

点击侧边栏的 Extensions 按钮。
Click the Extensions button in the Side Bar.
如果 Flutter 扩展显示有可用更新，点击更新按钮，然后重载。
If the Flutter extension is shown with an available update, click the update button and then the reload button.
重启 VS Code。
Restart VS Code.

创建项目

Creating projects

有几种方式创建一个新项目。

There are a couple ways to create a new project.

新建项目

Creating a new project

通过 Flutter 入门应用模板新建 Flutter 项目：

To create a new Flutter project from the Flutter starter app template:

打开命令面板（Ctrl+Shift+P （macOS 用 Cmd+Shift+P））。
Open the Command Palette (Ctrl+Shift+P (Cmd+Shift+P on macOS)).
选择 Flutter: New Project 命令然后按 Enter。
Select the Flutter: New Project command and press Enter.
选择 Application 然后按 Enter。
Select Application and press Enter.
选择 项目地址。
Select a Project location.
输入你想要的 项目名。
Enter your desired Project name.

从现有源代码打开项目

Opening a project from existing source code

打开现有 Flutter 项目：

To open an existing Flutter project:

在 IDE 主窗口点击 File > Open。
Click File > Open from the main IDE window.
选择存放现有 Flutter 源代码文件的目录。
Browse to the directory holding your existing Flutter source code files.
点击 Open。
Click Open.

编写代码及查看问题

Editing code and viewing issues

Flutter 扩展执行代码分析，它提供：

The Flutter extension performs code analysis that enables the following:

语法高亮。
Syntax highlighting
基于丰富输入分析的代码补全。
Code completions based on rich type analysis
导航到类型声明（Go to Definition 或 F12）和查找类型引用（Find All References 或 Shift+F12）。
Navigating to type declarations (Go to Definition or F12), and finding type usages (Find All References or Shift+F12)
查看所有当前代码问题（View > Problems 或 Ctrl+Shift+M (macOS 用 Cmd+Shift+M)）。所有问题分析都会在 Problems 面板展示：

Viewing all current source code problems (View > Problems or Ctrl+Shift+M (Cmd+Shift+M on macOS)) Any analysis issues are shown in the Problems pane:

运行和调试

Running and debugging

提示

有多种方式能够调试你的应用

You can debug your app in a couple of ways.

使用 DevTools，它是一个运行在浏览器中的调试以及性能测试工具集。DevTools 取代了前一代基于浏览器的性能测试工具 Observatory，它包含了以前仅适用于 Android Studio 和 IntelliJ 的功能，例如 Flutter inspector。
Using DevTools, a suite of debugging and profiling tools that run in a browser. DevTools replaces the previous browser-based profiling tool, Observatory, and includes functionality previously only available to Android Studio and IntelliJ, such as the Flutter inspector.
使用 VS Code 的内置调试功能，例如设置断点。
Using VS Code’s built-in debugging features, such as setting breakpoints.

以下说明描述了 VS Code 可用的功能。更多使用 DevTools 的详细信息请参考 DevTools 中的 Running DevTools from VS Code 文档。

The instructions below describe features available in VS Code. For information on using launching DevTools, see Running DevTools from VS Code in the DevTools docs.

在 IDE 主窗口点击 Run > Start Debugging 或按 F5 开启调试。

Start debugging by clicking Run > Start Debugging from the main IDE window, or press F5.

选择目标设备

Selecting a target device

当一个 Flutter 项目在 VS Code 中打开，你会在状态栏看到一些 Flutter 特有项，包括 Flutter SDK 版本和设备名称（或者无设备信息）：

When a Flutter project is open in VS Code, you should see a set of Flutter specific entries in the status bar, including a Flutter SDK version and a device name (or the message No Devices):

VS Code status bar

Flutter 扩展会自动选择上次连接的设备。然而，如果你有多个设备/模拟器连接，点击状态栏的 device 查看屏幕顶部的选择列表。选择你要用来运行或调试的设备。

The Flutter extension automatically selects the last device connected. However, if you have multiple devices/simulators connected, click device in the status bar to see a pick-list at the top of the screen. Select the device you want to use for running or debugging.

无断点运行

Run app without breakpoints

在 IDE 主窗口点击 Run > Start Without Debugging，或者按 Ctrl+F5，状态栏变橙色说明你正处于调试模式。

Click Run > Start Without Debugging in the main IDE window, or press Ctrl+F5. The status bar turns orange to show you are in a debug session.

断点运行

Run app with breakpoints

如果需要，在源代码中设置断点。
If desired, set breakpoints in your source code.
在 IDE 主窗口点击 Run > Start Debugging 或按 F5。
Click Run > Start Debugging in the main IDE window, or press F5.
- 左侧的调试侧边栏显示堆栈帧和变量。
  The left Debug Sidebar shows stack frames and variables.
- 底部的调试控制台面板显示输出的日志详情。
  The bottom Debug Console pane shows detailed logging output.
- 调试基于默认的配置。也可以通过点击调试侧边栏顶部的齿轮创建 launch.json 文件自定义调试。你可以修改里面的值。
  Debugging is based on a default launch configuration. To customize, click the cog at the top of the Debug Sidebar to create a launch.json file. You can then modify the values.

以调试 (debug)、性能 (profile) 或发布 (release) 模式运行应用

Run app in debug, profile, or release mode

Flutter 提供了很多种不同的构建模式运行你的应用，更多内容请参考文档 Flutter 的构建模式。

Flutter offers many different build modes to run your app in. You can read more about them in Flutter’s build modes.

打开 VS Code 里的 launch.json 文件
Open the launch.json file in VS Code.

如果你没有 launch.json 文件，请到 VS Code 的 Run 视图，点击 create a launch.json file 创建。
If you do not have a launch.json file, go to the Run view in VS Code and click create a launch.json file.
在 configurations 部分，修改 flutterMode 属性值为你想要的构建模式即可。
In the configurations section, change the flutterMode property to the build mode you want to target.
- 举个例子，如果你希望在调试模式下运行，你的 launch.json 文件应该类似下面这样：
  For example, if you want to run in debug mode, your launch.json might look like this:
```
  "configurations": [
   {
     "name": "Flutter",
     "request": "launch",
     "type": "dart",
     "flutterMode": "debug"
   }
 ]
```
在 Run 视图里运行你的应用。
Run the app through the Run view.

快速编辑和刷新开发周期

Fast edit and refresh development cycle

Flutter 提供一流的开发周期，通过 Stateful Hot Reload 特性使你在几乎修改代码的同时就能看到变化。详情请看使用热重载。

Flutter offers a best-in-class developer cycle enabling you to see the effect of your changes almost instantly with the Stateful Hot Reload feature. See Using hot reload for details.

进阶调试

Advanced debugging

以下的调试指南可能会对你有帮助：

You might find the following advanced debugging tips useful:

可视化布局问题调试

Debugging visual layout issues

在调试会话期间，命令面板和 Flutter inspector 会添加一些额外的调试命令，包括：

During a debug session, several additional debugging commands are added to the Command Palette and to the Flutter inspector. When space is limited, the icon is used as the visual version of the label.

切换 Baseline 绘制Toggle Baseline Painting

每个 RenderBox 在底部绘制一条线。

Causes each RenderBox to paint a line at each of its baselines.

切换重绘 RainbowToggle Repaint Rainbow

重新绘制时在图层上改变颜色。

Shows rotating colors on layers when repainting.

切换慢模式横幅Toggle Slow Animations

减慢动画以启用视觉检查。Slows down animations to enable visual inspection.

切换 debug 模式横幅显示Toggle Debug Mode Banner

在运行调试构建时隐藏 debug 模式的横幅 (banner)。

Hides the debug mode banner even when running a debug build.

调试外部库

Debugging external libraries

默认情况下，Flutter 扩展禁止调试外部库。启用步骤：

By default, debugging an external library is disabled in the Flutter extension. To enable:

选择 Settings > Extensions > Dart Configuration
Select Settings > Extensions > Dart Configuration.
勾选 Debug External Libraries 选项。
Check the Debug External Libraries option.

Flutter 代码编辑提示

Editing tips for Flutter code

如果你有其他我们应该提供的代码提示建议，请告诉我们！

If you have additional tips we should share, let us know!

代码辅助和快速修复

Assists & quick fixes

代码辅助功能是特定代码标识符相关的代码修改。当光标放在 Flutter widget 上时，黄色灯泡图标会指示可用的修改，可以通过点击灯泡进行修改，或者使用快捷键 Ctrl+. (macOS 用 Cmd+.)，如图所示：

Assists are code changes related to a certain code identifier. A number of these are available when the cursor is placed on a Flutter widget identifier, as indicated by the yellow lightbulb icon. The assist can be invoked by clicking the lightbulb, or by using the keyboard shortcut Ctrl+. (Cmd+. on Mac), as illustrated here:

Code assists

快速修复跟辅助类似，当一段代码有错误并且可以辅助修正时才会显示。

Quick fixes are similar, only they are shown with a piece of code has an error and they can assist in correcting it.

Widget 嵌套辅助

Wrap with new widget assist

当你有个 widget 想包装进一个容器 widget 时，例如你想把 widget 放入一个 Row 或者 Column。

This can be used when you have a widget that you want to wrap in a surrounding widget, for example if you want to wrap a widget in a Row or Column.

Widget 列表嵌套辅助

Wrap widget list with new widget assist

和上面的辅助类似，但它嵌套的是一个 widget 的列表，而不是单个的 widget。

Similar to the assist above, but for wrapping an existing list of widgets rather than an individual widget.

child 和 children 转换辅助

Convert child to children assist

将 child 转换成 children，并且把参数值写进一个 list。

Changes a child argument to a children argument, and wraps the argument value in a list.

StatelessWidget 到 StatefulWidget 的转换
创建 State 类并将代码移动过去，可以将 StatelessWidget 的实现更改为 StatefulWidget。

Convert StatelessWidget to StatefulWidget assist
Changes the implementation of a StatelessWidget to that of a StatefulWidget, by creating the State class and moving the code there.

代码片段

Snippets

代码片段可以用来加速输入通用类型代码段。通过输入前缀来调用，然后从代码完成窗口中选择：

Snippets can be used to speed up entering typical code structures. They are invoked by typing their prefix, and then selecting from the code completion window:

Snippets

Flutter 扩展包含以下片段：

The Flutter extension includes the following snippets:

前缀 stless：创建一个 StatelessWidget 子类。
Prefix stless: Create a new subclass of StatelessWidget.
前缀 stful：创建一个 StatefulWidget 子类，并且和 State 子类关联。
Prefix stful: Create a new subclass of StatefulWidget and its associated State subclass.
前缀 stanim：创建一个 StatefulWidget 子类，并且把包含字段初始化的 State 子类和一个 AnimationController 关联。
Prefix stanim: Create a new subclass of StatefulWidget, and its associated State subclass including a field initialized with an AnimationController.

你也可以通过在命令面板执行 Configure User Snippets 来自定义片段。

You can also define custom snippets by executing Configure User Snippets from the Command Palette.

键盘快捷键

Keyboard shortcuts

热重载
调试期间，在 调试工具栏 点击 热重载 (Hot Reload) 按钮，或者按 Ctrl+F5（macOS 用 Cmd+F5）执行热重载。

Hot reload
During a debug session, clicking the Hot Reload button on the Debug Toolbar, or pressing Ctrl+F5 (Cmd+F5 on macOS) performs a hot reload.

键位绑定可以在命令面板中使用 Open Keyboard Shortcuts 命令进行调整。

Keyboard mappings can be changed by executing the Open Keyboard Shortcuts command from the Command Palette.

热重载和热重启

Hot reload vs. hot restart

全部变量的初始化
Global variable initializers
静态变量的初始化
Static field initializers
应用的 main() 方法
The main() method of the app

对于这些更改，你无需结束调试过程而直接热重启 (hot restart) 你的应用。要执行热重启，执行命令面板的 Flutter：热重启命令，或者按 ``Ctrl+Shift+F5 (在 macOS 上使用 Cmd+Shift+F5)。

For these changes, fully restart your application without having to end your debugging session. To perform a hot restart, run the Flutter: Hot Restart command from the Command Palette, or press Ctrl+Shift+F5(Cmd+Shift+F5 on macOS).

故障排除

Troubleshooting

已知问题和反馈

Known issues and feedback

所有已知 bug 在这个 issue 列表中记录： Dart 和 Flutter 扩展 GitHub issue 追踪。

All known bugs are tracked in the issue tracker: Dart and Flutter extensions GitHub issue tracker.

我们非常欢迎 bugs/issues 和特性请求的反馈。在提交新 issue 之前：

We welcome feedback, both on bugs/issues and feature requests. Prior to filing new issues:

在 issue 列表中查找看该问题是否已被记录。
Do a quick search in the issue trackers to see if the issue is already tracked.
确保你已经更新最新版本插件。
Make sure you are up to date with the most recent version of the plugin.

提交新 issue 时，请包含 flutter doctor 输出。

When filing new issues, include flutter doctor output.

开发者工具概览

开发工具是什么？
What is DevTools?
我可以用开发工具来做什么？
What can I do with DevTools?
如何安装开发工具？
How do I install DevTools?
提交反馈
Providing feedback
其他资源
Other resources

开发工具是什么？

What is DevTools?

开发工具是一套 Dart 和 Flutter 的性能调试工具。目前已经“行进”到 Beta 版本了，但仍在正在持续开发中。

DevTools is a suite of performance and debugging tools for Dart and Flutter.

Dart DevTools Screens

我可以用开发工具来做什么？

What can I do with DevTools?

下面列出了一些可以用开发工具来实现的操作：

Here are some of the things you can do with DevTools:

检查 Flutter 应用程序的 UI 组件布局和状态；
Inspect the UI layout and state of a Flutter app.
在 Flutter 应用程序中诊断 UI 性能过低的问题；
Diagnose UI jank performance issues in a Flutter app.
Flutter 和 Dart 应用的 CPU 性能检测；
CPU profiling for a Flutter or Dart app.
为 Flutter 应用进行网络性能检测；
Network profiling for a Flutter app.
为 Flutter 或 Dart 应用进行源码级的调试；
Source-level debugging of a Flutter or Dart app.
在 Flutter 或 Dart 命令行应用中测试内存问题；
Debug memory issues in a Flutter or Dart command-line app.
View general log and diagnostics information about a running Flutter or Dart command-line app.
查看正在运行的 Flutter 或 Dart 的命令行应用程序相关的常规日志和诊断信息。
Analyze code and app size.

我们希望您将开发工具与现有的 IDE 或基于命令行的开发流程结合起来使用。

We expect you to use DevTools in conjunction with your existing IDE or command-line based development workflow.

如何安装开发工具？

How do I install DevTools?

查看 Android Studio/IntelliJ、VS Code 或命令行页面获取更多安装指导。

See the Android Studio/IntelliJ, VS Code, or command line pages for installation instructions.

提交反馈

Providing feedback

请在开发者工具 issue 追踪器中尝试使用开发工具，并提交反馈和文件 issue。

Please give DevTools a try, provide feedback, and file issues in the DevTools issue tracker. Thanks!

其他资源

Other resources

关于调试、分析 Flutter 应用程序的更多详细，请查阅调试页面，尤其是其他资源列表。

For more information on debugging and profiling Flutter apps, see the Debugging page and, in particular, its list of other resources.

如果你希望知道更多如何在命令行下使用开发者工具 (DevTools) 的话，请参考这个页面 Dart 开发者工具.

For more information on using DevTools with Dart command-line apps, see the DevTools documentation on dart.dev.

在 Android Studio 上安装和运行开发者工具

安装 Flutter 插件
Install the Flutter plugin
开始调试一个应用
Start an app to debug
从工具栏/菜单启动调试工具
Launch DevTools from the toolbar/menu
从事件 (action) 中启动调试工具
Launch DevTools from an action

安装 Flutter 插件

Install the Flutter plugin

请在第一次使用前安装 Flutter 插件，它可以在 Intellij 的 Plugins 或 Android Studio 的设置中开启，页面打开后便可以在 marketPlace 中找到 Flutter 插件。

Install the Flutter plugin if you don’t already have it installed. This can be done using the normal Plugins page in the IntelliJ and Android Studio settings. Once that page is open, you can search the marketplace for the Flutter plugin.

开始调试一个应用

Start an app to debug

需要在启动调试工具前开启一个 Flutter 应用，它可以通过打开 Flutter 项目实现，首先要确保你已经完成设备的连接，然后只需点击工具栏的 Run 或 Debug 按钮。

To open DevTools, you first need to run a Flutter app. This can be accomplished by opening a Flutter project, ensuring that you have a device connected, and clicking the Run or Debug toolbar buttons.

从工具栏/菜单启动调试工具

Launch DevTools from the toolbar/menu

应用启动后，你可以通过以下几种方式运行调试工具：

Once an app is running, you can start DevTools using one of the following:

运行界面下，在工具栏选择 Open DevTools（启动调试工具）。
Select the Open DevTools toolbar action in the Run view.
调试界面下，在工具栏选择 Open DevTools。
Select the Open DevTools toolbar action in the Debug view. (if debugging)
Flutter Inspector 里，在 More Actions 的菜单中选择 Open DevTools。
Select the Open DevTools action from the More Actions menu in the Flutter Inspector view.

screenshot of Open DevTools button

从事件 (action) 中启动调试工具

Launch DevTools from an action

你同样可以在 IntelliJ 中运行调试工具，先开启 Find Action… 对话框（Mac 上可以同时按下 ‘Command+Shift+A’)，然后查找 Open DevTools 选项。在调试工具已安装的前提下，相关服务会启动，同时打开指向待调试应用的浏览器实例。

You can also open DevTools from an IntelliJ action. Open the Find Action… dialog (on a Mac, press Command+Shift+A), and search for the Open DevTools action. When you select that action, DevTools is installed (if it isn’t already), the DevTools server launches, and a browser instance opens pointing to the DevTools app.

调试工具在 IntelliJ 事件启动时并不会直接连接到 Flutter 应用，因此当前应用的服务协议端口是必须的，你可以在 Connect to a running app 的对话框中开启。

When opened with an IntelliJ action, DevTools is not connected to a Flutter app. You’ll need to provide a service protocol port for a currently running app. You can do this using the inline Connect to a running app dialog.

在 VS Code 里安装和使用开发者工具

安装 VS Code 插件
Install the VS Code extensions
进行调试应用程序
Start an application to debug
启动开发工具
Launch DevTools

安装 VS Code 插件

Install the VS Code extensions

如果你想在 VS Code 中使用开发工具，你就一定需要安装 Dart 扩展。如果你还想要调试 Flutter 应用程序，那你还应该安装 Flutter 扩展。

To use the DevTools from VS Code, you need the Dart extension. If you’re debugging Flutter applications, you should also install the Flutter extension.

进行调试应用程序

Start an application to debug

通过在 VS Code 中打开你的项目的根目录（包含 pubspec.yaml）并点击 Run > Debugging (F5)，来开启调试会话。

Start a debug session for your application by opening the root folder of your project (the one containing pubspec.yaml) in VS Code and clicking Run > Start Debugging (F5).

启动开发工具

Launch DevTools

一旦调试会话处于活跃且应用程序已开启，那么 VS Code 命令控制板中将会显示 Dart: Open DevTools：

Once the debug session is active and the application has started, the Dart: Open DevTools command becomes available in the VS Code command palette:

Screenshot showing Open DevTools command

当你第一次运行时（以及未来更新开发工具包时），系统会提醒你激活或升级开发工具。

The first time you run this (and subsequently when the DevTools package is updated), you are prompted to activate or upgrade DevTools.

Screenshot showing Active DevTools command

接下来，开发工具将会在浏览器中启动，并自动连接至你的调试会话。

Clicking the Open button uses pub global activate to activate the DevTools package for you. Next, DevTools launches in your browser and automatically connects to your debug session.

Screenshot showing DevTools in a browser

当开发工具激活后，你将可以在 VS Code 的状态栏中看到它们。如果你已关闭浏览器选项卡，只要还有可用的 Dart/Flutter 调试会话，你也可以通过单击状态栏来重新启动浏览器。

While DevTools is active, you’ll see them in the status bar of VS Code. If you’ve closed the browser tab, you can click the status bar to re-launch your browser, so long as there’s still a suitable Dart/Flutter debugging session available.

Screenshot showing DevTools in the VS Code status bar

通过命令行安装和运行开发者工具

安装开发者工具
Install DevTools
启动开发者工具服务
Launch the DevTools application server
启动一个 app 来 debug
Start an application to debug
打开开发者工具并且连接到目标 app
Open DevTools and connect to the target app

安装开发者工具

Install DevTools

如果在你的环境变量 PATH 中有 dart, 可以运行：

If you have dart on your path, you can run the following command:

dart pub global activate devtools

如果在你的环境变量 PATH 中有 flutter, 可以运行：

If you have flutter on your path, you can run the following:

flutter pub global activate devtools

这个命令会在你的机器上安装（或升级）开发者工具。

That command installs (or updates) DevTools on your machine.

启动开发者工具服务

Launch the DevTools application server

下一步，启动本地 web server 服务来运行开发者工具。运行下面两个命令中的一个。

Next, run the local web server, which serves the DevTools application itself. To do that, run one of the following two commands:

dart pub global run devtools   # If you have `dart` on your path.

或者

flutter pub global run devtools   # If you have `flutter` on your path.

On the command line, you should see output that looks something like:

Serving DevTools at http://127.0.0.1:9100

启动一个 app 来 debug

Start an application to debug

下一步，启动并连接一个 app。可以是 Flutter app 或者一个 Dart 命令行应用。下面这个命令是启动一个 Flutter app:

Next, start an app to connect to. This can be either a Flutter application or a Dart command-line application. The command below specifies a Flutter app:

cd path/to/flutter/app
flutter run

运行 flutter run 时，你需要连接一个设备或者模拟器。当 app 启动后，你会在命令行中看到如下内容：

You need to have a device connected, or a simulator open, for flutter run to work. Once the app starts, you’ll see a message in your terminal that looks like the following:

An Observatory debugger and profiler on iPhone X is available
at: http://127.0.0.1:50976/Swm0bjIe0ks=/

记下这个 URL ，待会儿你可以使用它来连接 app 和开发者工具。

Keep note of this URL, as you will use it to connect your app to DevTools.

打开开发者工具并且连接到目标 app

Open DevTools and connect to the target app

上述完成后，使用开发者工具就会很简单，只需打开 chrome 并访问 http://localhost:9100。

Once it’s set up, using DevTools is as simple as opening a Chrome browser window and navigating to http://localhost:9100.

当这个网页打开后，你会看到一个链接对话框：

Once DevTools opens, you should see a connect dialog:

Screenshot of a logging view

将从启动 app 时获得的 URL 链接（在这个例子里是 http://127.0.0.1:50976/Swm0bjIe0ks=/ ）复制到这个链接对话框中来把你的 app 和开发者工具链接起来。

Paste the URL you got from running your app (in this example, http://127.0.0.1:50976/Swm0bjIe0ks=/) into the connect dialog to connect your app to DevTools.

这个链接包含一个秘钥 token，所以每次启动你的 app 时，链接都会改变。这意味着如果重启 app 后，你需要用新的 URL 链接来连接开发者工具。

This URL contains a security token, so it’s different for each run of your app. This means that if you stop your application and re-run it, you need to connect to DevTools with the new URL.

使用 Flutter inspector 工具

这是什么？
What is it?
开始使用
Get started
- 可视化地调试布局问题
  Debugging layout issues visually
检查一个 widget
Inspecting a widget
Flutter 布局浏览器
Flutter Layout Explorer
- 使用布局浏览器
  Using the Layout Explorer
  - 弹性布局
    Flex layouts
  - 固定大小布局
    Fixed size layouts
调试视觉效果
Visual debugging
树的详细信息
Details Tree
追踪 widget 创建
Track widget creation
其他资源
Other resources

这是什么？

What is it?

Flutter widget inspector 是一个强大的工具，用于可视化和查看 widget 树。 Flutter 框架层使用 widgets 作为核心构建模块来处理从控件（例如文本、按钮和切换等）到布局（例如居中、填充、行和列等）的所有内容。 Flutter inspector 不仅可以帮助你可视化查看 Flutter widget 树，还有其他的作用：

The Flutter widget inspector is a powerful tool for visualizing and exploring Flutter widget trees. The Flutter framework uses widgets as the core building block for anything from controls (such as text, buttons, and toggles), to layout (such as centering, padding, rows, and columns). The inspector helps you visualize and explore Flutter widget trees, and can be used for the following:

了解现有布局
understanding existing layouts
诊断布局问题
diagnosing layout issues

Screenshot of the Flutter inspector window

开始使用

Get started

要调试布局问题，请在 Debug 模式下运行应用程序，然后点击 DevTools 工具栏上的 Flutter inspector 选项打开调试面板。

To debug a layout issue, run the app in debug mode and open the inspector by clicking the Flutter Inspector tab on the DevTools toolbar.

可视化地调试布局问题

Debugging layout issues visually

下面是 Flutter inspector 工具栏中可用功能的指南。当空间有限时，将直接使用图标展示。

The following is a guide to the features available in the inspector’s toolbar. When space is limited, the icon is used as the visual version of the label.

选择 widget 模式
Select widget mode

启用此按钮以在设备上选择 widget 进行查看。有关更多信息，请参考查看 widget。

Enable this button in order to select a widget on the device to inspect it. For more information, see Inspecting a widget.

刷新树
Refresh tree

重新加载当前 widget 的信息。

Reload the current widget info

慢速动画
Slow Animations

以五分之一的速度运行动画以便对它们进行优化。

Run animations 5 times slower to help fine-tune them.

显示引导线
Show guidelines

覆盖一层引导线以帮助调整布局问题。

Overlay guidelines to assist with fixing layout issues.

显示基线
Show baselines

针对文字对齐展示文字的基线。对检查文字是否对齐有帮助。

Show baselines, which are used for aligning text. Can be useful for checking if text is aligned.

高亮重绘制内容
Highlight repaints

重新绘制时在图层上依次显示不同的颜色。

Shows rotating colors on layers when repainting.

高亮尺寸过大的图片
Highlight oversized images

在运行的应用程序中高亮并反转消耗过多内存的图像。

Highlights images that are using too much memory by inverting colors and flipping them.

Inspecting a widget

你可以浏览 widget 树并查看其附近的 widgets 和它们的属性值。

You can browse the interactive widget tree to view nearby widgets and see their field values.

要在 widget 树中找到单个 UI 元素，请点击工具栏中的 Select Widget Mode 按钮。这将使设备上的应用程序进入「widget select」模式。点击应用界面上的任何 widget，将选中 widget 并将 widget 树滚动到对应的节点。再次点击 Select Widget Mode 按钮则退出「widget select」模式。

To locate individual UI elements in the widget tree, click the Select Widget Mode button in the toolbar. This puts the app on the device into a “widget select” mode. Click any widget in the app’s UI; this selects the widget on the app’s screen, and scrolls the widget tree to the corresponding node. Toggle the Select Widget Mode button again to exit widget select mode.

在调试布局问题时，要查看的关键字段是 size 和 constraints。其中约束沿树结构向下传递，尺寸信息则向上返回。想要了解更多信息，可以查看深入理解 Flutter 布局约束。

When debugging layout issues, the key fields to look at are the size and constraints fields. The constraints flow down the tree, and the sizes flow back up. For more information on how this works, see Understanding constraints.

Flutter 布局浏览器

Flutter Layout Explorer

Flutter 布局浏览器可以帮助你更好地理解 Flutter 布局。

The Flutter Layout Explorer helps you to better understand Flutter layouts.

有关此工具的操作概述，观看 Flutter Explorer 的介绍视频：

For an overview of what you can do with this tool, see the Flutter Explorer video:

下面详细介绍的文章可能对你有帮助：

You might also find the following step-by-step article useful:

如何使用 Flutter Inspector 调试布局问题
How to debug layout issues with the Flutter Inspector

使用布局浏览器

Using the Layout Explorer

从 Flutter Inspector 中，选择一个 widget。布局浏览器支持弹性布局和固定大小的布局，并且针对它们配备了特定的工具。

From the Flutter Inspector, select a widget. The Layout Explorer supports both flex layouts and fixed size layouts, and has specific tooling for both kinds.

弹性布局

Flex layouts

当你选择了一个弹性布局 widget（例如，Row、Column、Flex）或它的子 widget 时，弹性布局工具将显示在布局浏览器中。

When you select a flex widget (for example, Row, Column, Flex) or a direct child of a flex widget, the flex layout tool will appear in the Layout Explorer.

布局浏览器会直观的显示 Flex widgets 及其子元素的布局方式。浏览器中还会显示主轴和交叉轴，以及每个轴当前的对齐方式（例如，start、end 和 spaceBetween）。它还显示了诸如弹性系数、弹性适配和布局约束等详细信息。

The Layout Explorer visualizes how Flex widgets and their children are laid out. The explorer identifies the main axis and cross axis, as well as the current alignment for each (for example, start, end, and spaceBetween). It also shows details like flex factor, flex fit, and layout constraints.

此外，浏览器中还会显示布局约束冲突和渲染溢出错误。正如你在设备上看到的那样，违背布局约束的地方会被标记成红色，溢出错误以标准的「黄色条带」显示。这些可视化的错误是为了让我们更好地理解溢出错误发生的原因，并了解如何修复它们。

Additionally, the explorer shows layout constraint violations and render overflow errors. Violated layout constraints are colored red, and overflow errors are presented in the standard “yellow-tape” pattern, as you might see on a running device. These visualizations aim to improve understanding of why overflow errors occur as well as how to fix them.

The Layout Explorer showing errors and device inspector

在 Select Widget Mode 模式下，点击布局浏览器中的 widget 会同步选择到设备上。启用此模式，请点击调试面板中的 Select Widget Mode 按钮。

Clicking a widget in the layout explorer mirrors the selection on the on-device inspector. Select Widget Mode needs to be enabled for this. To enable it, click on the Select Widget Mode button in the inspector.

The Select Widget Mode button in the inspector

你可以在布局浏览器的下拉列表修改属性值，例如弹性系数、弹性适配和对齐方式。当修改 widget 的属性时，您会看到新的值同时在浏览器和运行 Flutter 应用程序的设备上生效。浏览器通过动画使更改的效果清晰可见。从布局浏览器中对 widget 属性的更改不会修改源代码，将在热重载时还原。

For some properties, like flex factor, flex fit, and alignment, you can modify the value via dropdown lists in the explorer. When modifying a widget property, you see the new value reflected not only in the Layout Explorer, but also on the device running your Flutter app. The explorer animates on property changes so that the effect of the change is clear. Widget property changes made from the layout explorer don’t modify your source code and are reverted on hot reload.

交互属性

Interactive Properties

布局资源管理器支持修改 mainAxisAlignment、crossAxisAlignment 和 FlexParentData.flex。将来，我们可能会添加对其他属性的支持，例如 mainAxisSize、textDirection 和 FlexParentData.fit.

Layout Explorer supports modifying mainAxisAlignment, crossAxisAlignment, and FlexParentData.flex. In the future, we may add support for additional properties such as mainAxisSize, textDirection, and FlexParentData.fit.

mainAxisAlignment

The Layout Explorer changing main axis alignment

支持属性：

Supported values:

MainAxisAlignment.start
MainAxisAlignment.end
MainAxisAlignment.center
MainAxisAlignment.spaceBetween
MainAxisAlignment.spaceAround
MainAxisAlignment.spaceEvenly

crossAxisAlignment

The Layout Explorer changing cross axis alignment

支持属性：

Supported values:

CrossAxisAlignment.start
CrossAxisAlignment.center
CrossAxisAlignment.end
CrossAxisAlignment.stretch

FlexParentData.flex

The Layout Explorer changing flex factor

布局浏览器支持设置 7 种弹性因子（null、0、1、2、3、4、5），但从技术上讲，弹性 widget 子级的弹性因子可以是任何整数。

Layout Explorer supports 7 flex options in the UI (null, 0, 1, 2, 3, 4, 5), but technically the flex factor of a flex widget’s child can be any int.

Flexible.fit

The Layout Explorer changing fit

布局浏览器支持两种不同类型的 FlexFit：loose 和 tight。

Layout Explorer supports the two different types of FlexFit: loose and tight.

固定大小布局

Fixed size layouts

当您选择一个固定大小的 widget 而不是弹性 widget 时，它的布局信息将显示在布局浏览器中。你可以看到所选 widget 及其最近的上一级 RenderObject 的大小、约束和填充信息。

When you select a fixed size widget that is not a child of a flex widget, fixed size layout information will appear in the Layout Explorer. You can see size, constraint, and padding information for both the selected widget and its nearest upstream RenderObject.

The Layout Explorer fixed size tool

调试视觉效果

Visual debugging

Flutter Inspector 提供了多种以可视化方式调试应用的方式。以下是在 Flutter DevTools 中的 inspector 可用的选项：

The Flutter Inspector provides several options for visually debugging your app. These are the options available from the inspector within Flutter DevTools.

慢速动画

Slow animations

启用时，动画将以约五分之一的原有速度运行，方便对视觉效果进行检查。当你想要仔细地观察并调试看起来不正常的动画时，这个选项会非常有用。

When enabled, this option runs animations 5 times slower for easier visual inspection. This can be useful if you want to carefully observe and tweak an animation that doesn’t look quite right.

你也可以使用代码设置：

This can also be set in code:

import 'package:flutter/scheduler.dart';

void setSlowAnimations() {
  timeDilation = 5.0;
}

这会让动画时长增加 5 倍（速度减慢 5 倍）。

This slows the animations by 5x.

显示引导线

Show guidelines

该功能会在你的应用顶层绘制引导线，展示绘制区域、对齐、间距、滚动视图、裁剪和空位填充。

This feature draws guidelines over your app that display render boxes, alignments, paddings, scroll views, clippings and spacers.

这个工具能帮助你更加了解你的布局。例如查找不需要的填充或者理解 widget 的对齐方式。

This tool can be used for better understanding your layout. For instance, by finding unwanted padding or understanding widget alignment.

你也可以通过代码启用：

You can also enable this in code:

import 'package:flutter/rendering.dart';

void showLayoutGuidelines() {
  debugPaintSizeEnabled = true;
}

Render boxes

RenderBox

绘制在屏幕上的 widgets 会创建一个 RenderBox，它是 Flutter 布局的基础构建。这些 RenderBox 会加上一个浅蓝色的边框：

Widgets that draw to the screen create a render box, the building blocks of Flutter layouts. They’re shown with a bright blue border:

Screenshot of render box guidelines

对齐方式

Alignments

对齐方式将以黄色箭头展示。这些箭头会显示出垂直和竖屏方向上 widget 相对其父布局的偏移。例如，这个按钮图标有四个箭头表示它被居中展示：

Alignments are shown with yellow arrows. These arrows show the vertical and horizontal offsets of a widget relative to its parent. For example, this button’s icon is shown as being centered by the four arrows:

Screenshot of alignment guidelines

间距

Padding

间距会以半透明的蓝色背景显示：

Padding is shown with a semi-transparent blue background:

Screenshot of padding guidelines

滚动视图

Scroll views

包含滚动内容的 widget（例如 ListView）会展示绿色的箭头：

Widgets with scrolling contents (such as list views) are shown with green arrows:

Screenshot of scroll view guidelines

裁剪

Clipping

使用了诸如 ClipRect Widget 进行裁剪的内容，会以粉红色的虚线加一个剪刀图标展示：

Clipping, for example when using the ClipRect widget, are shown with a dashed pink line with a scissors icon:

Screenshot of clip guidelines

空位填充

Spacers

空位填充的 widgets 会以灰色背景展示，例如没有 child 的 SizedBox：

Spacer widgets are shown with a grey background, such as this SizedBox without a child:

显示基线

Show baselines

该选项会显示所有的基线。基线是水平的用来定位文字的线。

This option makes all baselines visible. Baselines are horizontal lines used to position text.

在检查文字是否垂直对齐时，基线会非常有用。例如，下图中文字的基线稍微有一些错位：

This can be useful for checking whether text is precisely aligned vertically. For example, the text baselines in the following screenshot are slightly misaligned:

Screenshot with show baselines enabled

Baseline widget 可以用来调整基线。

The Baseline widget can be used to adjust baselines.

在设置了基线的 RenderBox 上，都会显示一条线。字母的基线以绿色展示，而符号的基线以黄色展示。

A line is drawn on any render box that has a baseline set; alphabetic baselines are shown as green and ideographic as yellow.

你也可以通过代码启用：

You can also enable this in code:

import 'package:flutter/rendering.dart';

void showBaselines() {
  debugPaintBaselinesEnabled = true;
}

高亮重绘制内容

Highlight repaints

该选项会为所有的 RenderBox 绘制一层边框，在它们重新绘制时改变颜色。

This option draws a border around all render boxes that changes color every time that box repaints.

以彩虹色谱循环的颜色，有利于你找到应用中频繁重绘导致性能消耗过大的部分。

This rotating rainbow of colors is useful for finding parts of your app that are repainting too often and potentially harming performance.

例如，一个小动画可能会导致整个页面一直在重绘。将动画使用 RepaintBoundary widget 嵌套，可以保证动画只会导致其本身重绘。

For example, one small animation could be causing an entire page to repaint on every frame. Wrapping the animation in a RepaintBoundary widget limits the repainting to just the animation.

下面是一个进度指示器导致其容器重绘的例子：

Here the progress indicator causes its container to repaint:

class EverythingRepaintsPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Repaint Example')),
      body: Center(
        child: CircularProgressIndicator(),
      ),
    );
  }
}

Screen recording of a whole screen repainting

将进度指示器使用 RepaintBoundary 包裹，可以将重绘范围缩小至它本身占有的区域。

Wrapping the progress indicator in a RepaintBoundary causes only that section of the screen to repaint:

class AreaRepaintsPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Repaint Example')),
      body: Center(
        child: RepaintBoundary(
          child: CircularProgressIndicator(),
        ),
      ),
    );
  }
}

Screen recording of a just a progress indicator repainting

RepaintBoundary widget 也有一些额外的消耗。它们对性能有一定的帮助，但也会在创建额外的绘制画布时增加一定的内存消耗。

RepaintBoundary widgets have tradeoffs. They can help with performance, but they also have an overhead of creating a new canvas, which uses additional memory.

你也可以通过代码启用：

You can also enable this option in code:

import 'package:flutter/rendering.dart';

void highlightRepaints() {
  debugRepaintRainbowEnabled = true;
}

高亮尺寸过大的图片

Highlight oversized images

该选项会将尺寸过大的图片高亮表示，并且进行垂直翻转及色调反转：

This option highlights images that are too large by both inverting their colors and flipping them vertically:

A highlighted oversized image

被高亮的图片使用了过多的内存。例如一张 5MB 大小的图片以 100x100 像素展示。

The highlighted images use more memory than is required; for example, a large 5MB image displayed at 100 by 100 pixels.

这样的图片会导致性能低下，在低端设备上尤为明显，而当你在诸如列表中有大量这样的图片时，性能的下降会叠加。调试控制台窗口中会打印每个图片的信息：

Such images can cause poor performance, especially on lower-end devices and when you have many images, as in a list view, this performance hit can add up. Information about each image is printed in the debug console:

dash.png has a display size of 213×392 but a decode size of 2130×392, which uses an additional 2542KB.

超过 128KB 的图片会被视为过大。

Images are deemed too large if they use at least 128KB more than required.

调整图片

Fixing images

在可能的情况下，最好的办法是调整图片资源的大小，让它变得更小。

Wherever possible, the best way to fix this problem is resizing the image asset file so it’s smaller.

如果该方法不可行，你可以使用 Image 构造里的 cacheHeight 和 cacheWidth 参数：

If this isn’t possible, you can use the cacheHeight and cacheWidth parameters on the Image constructor:

class ResizedImage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Image.asset(
      'dash.png',
      cacheHeight: 213,
      cacheWidth: 392,
    );
  }
}

这样的方法可以让引擎以指定的大小解析图片，减少内存的消耗（解析开销和空间占用相较图片调整图片本身仍然较大）。无论如何设置参数，图片依然会以布局限制或大小进行渲染。

This makes the engine decode this image at the specified size, and reduces memory usage (decoding and storage is still more expensive than if the image asset itself was shrunk). The image is rendered to the constraints of the layout or width and height regardless of these parameters.

该属性同样可以使用代码设置：

This property can also be set in code:

import 'package:flutter/painting.dart';

void showOversizedImages() {
  debugInvertOversizedImages = true;
}

More information

以下的链接提供了更多细节内容：

You can learn more at the following link:

Flutter 文档：debugInvertOversizedImages
Flutter documentation: debugInvertOversizedImages

树的详细信息

Details Tree

选择 Details Tree 标签展示选中 widget 的树结构的详细信息。

Select the Details Tree tab to display the details tree for the selected widget.

The Details Tree tab

从树的详细信息中，你可以获取有关 widget 的属性、渲染对象和子节点等有用信息。

From the details tree, you can gather useful information about a widget’s properties, render object, and children.

The Details Tree view

Track widget creation

Flutter inspector 的部分功能是基于检测应用程序的源码，以便更好地理解创建 widget 的源位置。 Flutter inspector 可以以类似于在源代码中定义 UI 的方式呈现 widget 树。如果没有它，widget 树中的组成某个节点的树结构会更深，并且更难理解运行时 widget 的层次结构如何与应用程序的 UI 相对应。

Part of the functionality of the Flutter inspector is based on instrumenting the application code in order to better understand the source locations where widgets are created. The source instrumentation allows the Flutter inspector to present the widget tree in a manner similar to how the UI was defined in your source code. Without it, the tree of nodes in the widget tree are much deeper, and it can be more difficult to understand how the runtime widget hierarchy corresponds to your application’s UI.

你可以通过在 flutter run 后面添加参数 -no track widget creation 来禁用此功能。

You can disable this feature by passing --no-track-widget-creation to the flutter run command.

下面是 widget 树在启用和不启用追踪 widget 创建下的示例。

Here are examples of what your widget tree might look like with and without track widget creation enabled.

启用追踪 widget 创建（默认）：

Track widget creation enabled (default):

The widget tree with track widget creation enabled

关闭追踪 widget 创建（不推荐）：

Track widget creation disabled (not recommended):

The widget tree with track widget creation disabled

此功能可避免在调试构建中将其他相同的 const 的 Widgets 视为相同。有关更多详细信息，请参阅关于调试时常见问题的讨论。

This feature prevents otherwise-identical const Widgets from being considered equal in debug builds. For more details, see the discussion on common problems when debugging.

其他资源

Other resources

有关 Flutter inspector 常用功能的演示，请参考 DartConf 2018 talk 中基于 IntelliJ 上的演示。

For a demonstration of what’s generally possible with the inspector, see the DartConf 2018 talk demonstrating the IntelliJ version of the Flutter inspector.

Using the Performance view

Contents

What is it?
Flutter frames chart
- UI
- Raster
- Jank
Timeline events chart
CPU Profiler
Import and export

What is it?

The performance view offers timing and performance information for activity in your application. It consists of three parts, each increasing in granularity.

Flutter frames chart (Flutter apps only)
Timeline events chart
CPU profiler

The performance view also supports importing and exporting of data snapshots. For more information, see the Import and export section.

Flutter frames chart

This chart contains Flutter frame information for your application. Each bar set in the chart represents a single Flutter frame. The bars are color-coded to highlight the different portions of work that occur when rendering a Flutter frame: work from the UI thread and work from the raster thread (previously known as the GPU thread).

Screenshot from a performance snapshot

Selecting a bar from this chart centers the flame chart below on the timeline events corresponding to the selected Flutter frame. The events are highlighted with blue brackets.

Screenshot from a timeline recording

UI

The UI thread executes Dart code in the Dart VM. This includes code from your application as well as the Flutter framework. When your app creates and displays a scene, the UI thread creates a layer tree, a lightweight object containing device-agnostic painting commands, and sends the layer tree to the raster thread to be rendered on the device. Do not block this thread.

Raster

The raster thread (previously known as the GPU thread) executes graphics code from the Flutter Engine. This thread takes the layer tree and displays it by talking to the GPU (graphic processing unit). You cannot directly access the raster thread or its data, but if this thread is slow, it’s a result of something you’ve done in the Dart code. Skia, the graphics library, runs on this thread.

Sometimes a scene results in a layer tree that is easy to construct, but expensive to render on the raster thread. In this case, you need to figure out what your code is doing that is causing rendering code to be slow. Specific kinds of workloads are more difficult for the GPU. They might involve unnecessary calls to saveLayer(), intersecting opacities with multiple objects, and clips or shadows in specific situations.

For more information on profiling, see Identifying problems in the GPU graph.

Jank

The frame rendering chart shows jank with a red overlay. A frame is considered to be janky if it takes more than ~16 ms to complete (for 60 FPS devices). To achieve a frame rendering rate of 60 FPS (frames per second), each frame must render in ~16 ms or less. When this target is missed, you may experience UI jank or dropped frames.

For more information on how to analyze your app’s performance, see Flutter performance profiling.

Timeline events chart

The timeline events chart shows all event tracing from your application. The Flutter framework emits timeline events as it works to build frames, draw scenes, and track other activity such as HTTP traffic. These events show up here in the Timeline. You can also send your own Timeline events via the dart:developer Timeline and TimelineTask APIs.

Screenshot of timeline events for a frame

The flame chart supports zooming and panning:

To zoom, scroll up and down with the mouse wheel / trackpad
To pan horizontally, either click and drag the chart or scroll horizontally with the mouse wheel / trackpad
To pan vertically, either click and drag the chart or use alt + scroll
The WASD keys also work for controlling zoom and horizontal scroll position

You can click an event to view CPU profiling information in the CPU profiler below, described in the next section.

CPU Profiler

Start recording a CPU profile by clicking Record. When you are done recording, click Stop. At this point, CPU profiling data is pulled from the VM and displayed in the profiler views (Call Tree, Bottom Up, and Flame Chart).

Profile granularity

The default rate at which the VM collects CPU samples is 1 sample / 250 μs. This is selected by default on the CPU profiler view as “Profile granularity: medium”. This rate can be modified via the selector at the top of the page. The sampling rates for low, medium, and high granularity are 1 / 1000 μs, 1 / 250 μs, and 1 / 50 μs, respectively. It is important to know the trade-offs of modifying this setting.

A higher granularity profile has a higher sampling rate, and therefore yields a fine-grained CPU profile with more samples. This may also impact performance of your app since the VM is being interrupted more often to collect samples. This also causes the VM’s CPU sample buffer to overflow more quickly. The VM has limited space where it can store CPU sample information. At a higher sampling rate, the space fills up and begins to overflow sooner than it would have if a lower sampling rate was used. This means that you may not have access to CPU samples from the beginning of the recorded profile.

A lower granularity profile has a lower sampling rate, and therefore yields a coarse-grained CPU profile with fewer samples. However, this impacts your app’s performance less. The VM’s sample buffer also fills more slowly, so you can see CPU samples for a longer period of app run time. This means that you have a better chance of viewing CPU samples from the beginning of the recorded profile.

Flame chart

This tab of the profiler shows CPU samples for the recorded duration. This chart should be viewed as a top-down stack trace, where the top-most stack frame calls the one below it. The width of each stack frame represents the amount of time it consumed the CPU. Stack frames that consume a lot of CPU time may be a good place to look for possible performance improvements.

Screenshot of a flame chart

Call tree

The call tree view shows the method trace for the CPU profile. This table is a top-down representation of the profile, meaning that a method can be expanded to show its callees.

Total time: Time the method spent executing its own code as well as the code for its callees.
Self time: Time the method spent executing only its own code.
Method: Name of the called method.
Source: File path for the method call site.

Screenshot of a call tree table

Bottom up

The bottom up view shows the method trace for the CPU profile but, as the name suggests, it’s a bottom-up representation of the profile. This means that each top-level method in the table is actually the last method in the call stack for a given CPU sample (in other words, it’s the leaf node for the sample).

In this table, a method can be expanded to show its callers.

Total time

Time the method spent executing its own code as well as the code for its callee.

Self time

For top-level methods in the bottom-up tree (leaf stack frames in the profile), this is the time the method spent executing only its own code. For sub nodes (the callers in the CPU profile), this is the self time of the callee when being called by the caller. In the following example, the self time of the caller createRenderObject is equal to the self time of the callee debugCheckHasDirectionality when being called by the caller.

Method

Name of the called method.

Source

File path for the method call site.

Screenshot of a bottom up table

Import and export

DevTools supports importing and exporting performance snapshots. Clicking the export button (upper-right corner above the frame rendering chart) downloads a snapshot of the current data on the performance page. To import a performance snapshot, you can drag and drop the snapshot into DevTools from any page. Note that DevTools only supports importing files that were originally exported from DevTools.

使用内存视图 (Memory view)

这是什么？
What is it?
DevTools 内存分析页面
DevTools memory page
绘制内存统计信息和事件图表
Charting memory statistics and events
分析和快照
Analysis and snapshots
分配和跟踪
Allocations and tracking
内存剖析图
Memory anatomy
- 事件窗格
  Events Pane
- 添加自定义事件到时间线
  Adding user custom events to the timeline
内存概览图
Memory overview chart
- 悬浮窗
  Hover card
- Android 图表
  Android chart
内存控制
Memory controls
内存相关操作
Memory actions
快照
Snapshots
检查快照中的类实例
Inspecting a class instance in a snapshot
快照分析
Analysis of a snapshot
Allocation 选项
Allocation tab
分配跟踪
Allocation tracking
筛选、搜索和自动补全
Filtering, Searching and Auto-Complete
- 筛选
  Filtering
- 设置
  Setting
内存问题案例学习
Memory problem case study
虚拟机术语表
Glossary of VM terms

这是什么？

What is it?

使用类构造函数创建的 Dart 对象（例如，使用 new MyClass() 或 MyClass()）会被分配在称为堆的内存区域中。堆中的内存由 Dart VM（虚拟机）管理。

Allocated Dart objects created using a class constructor (for example, by using new MyClass() or MyClass()) live in a portion of memory called the heap. The memory in the heap is managed by the Dart VM (virtual machine).

DevTools 内存分析页面

DevTools memory page

你可以在 DevTools 中的内存分析页面观察在给定的时段内 isolate 在怎样使用内存。

DevTools Memory page lets you peek at how an isolate is using memory at a given moment.

DevTools 中的内存分析包括 3 个主要功能：

Memory profiling in DevTools consists of 3 main functions:

绘制内存使用统计数据和事件图表
Charting memory usage statistics and events
通过查看堆中的所有内存，来检测内存问题和检查对象
Anaylsis to view all memory via a heap to detect memory issues and inspect objects
分配时监控和跟踪（堆栈跟踪）特定类和对象的分配
Allocations to monitor and track (stack trace) specific classes and objects when an allocation occurs

绘制内存统计信息和事件图表

Charting memory statistics and events

当选中顶部 tab 中的 Memory（内存）选项时，DevTools 将收集来自 VM 的内存统计数据。这些统计数据显示在两个概览图（Dart 内存以及 Android 图表）中，记录了一般内存的使用情况，例如使用的总堆、外部堆、最大堆容量、常驻集大小（RSS）。当你与应用程序交互时，会触发各种事件，例如内存 GC（垃圾回收）、Flutter 事件、用户触发的事件（使用 dart:developer 包）与内存统计数据会被记录在同一时间线中。所有这些收集的统计数据和事件都显示在图表中，请参见内存剖析。

At the top-level, when the memory tab is selected memory statistics from the VM are collected. These statistics are displayed in the two overview charts (Dart memory and Android-only) the collection of general memory usage e.g., total heap used, external heap, maximum heap capacity, Resident Set Size (RSS). As you interact with your application various events are detected e.g., memory GC (garabage collection),Flutter events, user fired events (using the dart:developer package) are collected in the same timeline as the memory statistics. All of this collected statistics and events are displayed in charts see Memory anatomy.

分析和快照

Analysis and snapshots

快照是 Dart 内存堆中所有对象最复杂和最耗时的完整视图。每次保存快照时，都会对收集的内存数据进行分析。该分析会尝试识别任何可能导致应用程序内存泄漏或崩溃的内存模式。例如，为缩略图大小的图片加载大型资源是低效的，可以通过加载较小的资源或调整 cacheWidth/cacheHeight，减小图片的解码大小，降低 ImageCache 的内存使用，以此提高内存使用率。你可以在 Analysis 选项中查看分析捕捉到的问题。

A Snapshot is a complete, the most complex and time consuming view of all objects in the Dart memory heap. Each time a snapshot is taken, an analysis is performed over the collected memory data. The analysis attempts to identify any memory patterns that may cause leaks or lead to application crashes. For example, loading large assets for thumbnail-sized images inefficiently, memory usage can be improved by loading smaller assets or adjusting the cacheWidth/cacheHeight to decode an image to a smaller size reducing the memory usage of the ImageCache. The analysis catches issues like this see Analysis tab.

分配和跟踪

Allocations and tracking

在你感兴趣的时间周期内，监控所有直接与 DevTools 或应用程序交互时涉及到的内存分配。你可以了解分配了多少对象、多少字节，或者跟踪代码中特定类的所有分配位置。此信息可在内存分析页面的 Allocations（分配） 选项下查看，与使用快照相比，它的速度相当快，开销也更小。

Monitoring all allocations involes you directly interacting with DevTools and your application to isolate a short period of time that you are interested in knowing how many objects were allocated, how many bytes were allocated, or tracking all the places in your code where a particular class is allocated. This information is available under the “Allocations” tab of Memory profiler and his a fairly fast with less overhead than using a snapshot.

监控分配和重置累计数据，有助于在点击重置和监视跟踪之间的短时间内分析累计数据（分配的对象数或字节数）。如果你怀疑应用程序发生了内存泄漏或存在与内存分配相关的其他错误，累计数据可以帮助你了解内存分配的速率。此外，跟踪几个特定类的能力，可能会减慢应用程序的运行。VM 在调用类的构造函数（分配）时记录堆栈跟踪。可以在分配内存时找到代码中的确切位置。请参阅 Allocation 选项。

Monitoring allocations and resetting of accumulators, helps to analyze the accumulator counts (number of objects or bytes allocated) in a short timeframe between a reset and monitor Track events. The accumulators can be used to understand the rate of memory allocations. If you suspect your application is leaking memory or has other bugs relating to memory allocation. Additionally, the ability to track a few specific classes, too many may slow the running of your application. The VM records the stack trace at the time a class’ constructor (allocation) is called. This can isolate the exact location in your code when/where memory is being allocated. See Allocation tab.

提示

对正在运行的应用程序进行性能分析时，请使用 profile 模式。除非你的应用程序以 profile 模式运行，否则不能看做 release 版本的内存性能表现。一般来说，在 debug、release 和 profile 模式之间，相对而言，内存的使用是相当准确的。因为 profile 模式创建了 service isolate 来配置应用程序，可能会显示更高的绝对内存使用率。此 isolate 在 release 模式下不存在。debug 模式下使用的绝对内存也可能高于 release 模式。 release 模式可以提前运行和优化任务，而在 debug 模式中，同样的任务必须实时运行，这需要更多信息。

Use profile mode when running your app to analyze performance. Memory usage is not indicative of release performance unless your application is run in profile mode. In general, memory usage is fairly accurate, in relative terms, between debug, release, or profile modes. Profile mode might show higher absolute memory usage because a service isolate is created to profile your application. This isolate won’t exist in release mode. Absolute memory used might also be higher in debug versus release mode. In release mode, work can be computed and optimized ahead of time, while in debug mode that same work might have to be computed at runtime, requiring more information.

内存剖析图

Memory anatomy

时间序列图用于显示连续时间间隔的 Flutter 内存状态。图表上的每个数据点表示相应时间戳（x 轴）下堆的测量值（y 轴），例如，使用率、容量、外部内存、垃圾收集和常驻集大小。

A timeseries graph is used to visualize the state of the Flutter memory at successive intervals of time. Each data point on the chart corresponds to the timestamp (x-axis) of measured quantities (y-axis) of the heap, for example, usage, capacity, external, garbage collection, and resident set size.

Screenshot of a memory anatomy page

事件窗格

Events Pane

同一个时间轴上会显示 Dart VM 和 DevTools 事件。这些事件包含快照（手动和自动）、Dart VM 自动 GC、手动 GC 或者监控和累计数据的重置操作。

The event timeline displays Dart VM and DevTools events on a shared timeline. These events can be snapshots (manual and auto), Dart VM GCs, user requested GCs, or monitor and accumulator reset actions.

Screenshot of DevTools events

此图表显示与内存图表时间线相关的 DevTools 事件（如手动 GC、VM GC、快照、监控分配跟踪和重置累计数据按钮单击）。点击事件时间线中的标记，将显示事件发生时间的悬浮窗。这可能有助于判断时间轴（x 轴）中何时发生内存泄漏。

This chart displays DevTools events (such as manual GC, VM GC, Snapshot, monitor Allocations Track and Reset of accumulators button clicks) in relation to the memory chart timeline. Clicking over the markers in the Event timeline displays a hover card of the time when the event occurred. This may help identify when a memory leak might have occurred in the timeline (x-axis).

Screenshot of the event timeline legend

下面是图例中每个 DevTools 事件的符号及其含义

This legend shows the symbol for each DevTools event and its meaning

Snapshot Snapshot（手动快照）

User Snapshot

用户主动保存的快照，可以收集所有内存信息并进行分析。

User initiated snapshot—all memory information collected and an analysis performed.

Auto-Snapshot Auto-Snapshot（自动快照）

Auto Snapshot

当检测到内存比以前的大小增加了 40% 或更多时 DevTools 会自动保存一个快照。可以用于快速检测 Flutter 应用程序中的内存峰值，以供后续分析（与手动快照中收集的信息相同）。

DevTools initiated a snapshot detecting that memory grow by 40% or more from previous size. This is used to quickly detect memory spikes in your Flutter application for later analysis (same information collected in a manual snapshot).

Track Track（跟踪）

Monitor

收集当前所有处于活动状态的类的状态实例数和所有实例的字节大小。此外，变化值是自上次按下 Reset(重置) 按钮以来累计数据的变化。

Collects current state of all active classes number of instances and byte size of all instances. In addition, the deltas are the change in the accumulators since the last “Reset” button pressed.

Reset Reset（重置）

Reset

实例和字节的累计数据都重置为零时。

When both the instance and bytes accumulators were reset to zero.

User Initiated GC User Initiated GC（用户手动 GC）

用户向 VM 请求执行内存 GC（仅向 VM 建议，不一定立刻执行）。

User initiated request to VM to to perform a garbage collection of memory (only a suggestion to the VM).

VM GC VM GC（VM 自动 GC）

VM GC

VM 自动执行 GC，释放不再使用的空间。更多 Dart 是如何执行垃圾收集的信息，参阅不要担心 GC。

GC (VM garbage collection) has occurred, frees space no longer used. For more information on how Dart performs garbage collection, see Don’t Fear the Garbage Collector.

User and Flutter Event User and Flutter Event（用户和 Flutter 事件）

在事件窗格中显示为三角形。深色三角形表示「多个 Flutter 或用户事件」。

Displayed as a triangle in the event pane. The dark magenta triangle “Multiple Flutter or User Events”

Aggregate Events

标识在此时间戳接收的多个事件。浅色三角形表示「一次 Flutter 或用户事件」。

identifies more than one event was received at this timestamp. The lighter magenta triangle “One Flutter or User Event”

Single Events

表示在此时间戳处仅收到一个事件。要查看事件，点击三角形将显示悬浮窗，展开浮窗底部，将显示该时间戳的所有事件。

indicates only one event was received at this timestamp. To view the events clicking on the triangle will display a hover card and expanding the events at the bottom of the hovercard will display all events for that timestamp.

事件窗格下方显示的是内存图表和 Android 内存图表。只有 Android 应用程序才会展示，它显示了 ADB 应用程序摘要中的 Android ADB 内存信息。

Displayed below the events pane is the memory chart and the Android memory chart. The android-memory chart is specific to an Android app, and it shows Android ADB meminfo from an ADB app summary.

添加自定义事件到时间线

Adding user custom events to the timeline

有时可能很难将 Flutter 应用程序代码中的操作与内存时间线图中绘制的内存数据或者事件关联起来。你可以将自定义的事件发送到 内存分析 时间线中，来了解代码中发生了什么。这会帮助你了解应用程序在 Dart/Flutter 框架中的内存使用情况（堆）。

Sometimes it may be difficult to correlate the actions in your Flutter application code and the collected memory statistics/events charted in the Memory timeline/chart. To help know what’s happening in your code your own events can be injected into the Memory Profile timeline to help to understand how your application’s memory usage is performing within the Dart/Flutter framework (heap).

使用 dart:developer 包的 postEvent 方法发布你的自定义事件。需要注意的是，事件名称的前缀必须为 DevTools.Event_，然后附加事件的名称。例如 DevTools.Event_MyEventName 。

Posting your own custom event(s) are done using the dart:developer package postEvent method. In particular, the event name must be prefixed with DevTools.Event_ then your event name would be appended e.g., DevTools.Event_MyEventName

使用时你需要在代码中添加下方的导入信息：

To use add the following import to your code:

import 'dart:developer' as developer;

以及将自定义事件发布到内存时间线的方法：

and a method to post custom event(s) to the Memory timeline:

  void devToolsPostEvent(String eventName, Map<String, Object> eventData) {
    developer.postEvent('DevTools.Event_$eventName', eventData);
  }

要从代码中发布事件，可以调用 devToolsPostEvent。例如，在函数 recordLoadedImage 中，可以通过 method（recordLoadedImage）以及 param（URL）参数将 MyImages 事件发布到内存（事件）时间线。

Then to post an event from your code you would call the devToolsPostEvent e.g. In your function recordLoadedImage you could cause the ‘MyImages’ event to be posted to the Memory (event) timeline with the values method and param (the URL).

  Widget recordLoadedImage(ImageChunkEvent imageChunkEvent, String imageUrl) {
 
    // Record the event in the memory event pane.
    devToolsPostEvent('MyFirstApp', { 'method': 'recordLoadedImage', 'param': imageUrl });

    if (imageChunkEvent == null) return null;

    ...

  }

点击事件窗格中的多事件三角形，将显示包含所有事件详细信息的悬浮窗，例如，在 04:36:21 时刻的两个自定义事件，事件名称为「MyFirstApp」，两个字段 method 和 param 显示事件的对应值：

Clicking on the aggregated event triangle in the event pane will dispay a hover card with the details of all events e.g., two custom events at the timestamp 04:36:21 with the event name ‘MyFirstApp’ and the two eventData entries method and param are displayed with their values:

Hover Card Custom Events

滑动事件显示：

Scrolling the events displays:

Custom Events Details

内存概览图

Memory overview chart

采集的内存数据的时间序列图，用于观察随时间变化的 Dart/Flutter 堆和本机内存的状态。

A timeseries graph of collected memory statistics, to visualize the state of the Dart/Flutter heap and Dart/Flutter native memory over time.

图表的 x 轴是事件的时间线（时间序列）。在 y 轴上绘制的数据在收集数据时都有时间戳。换句话说，这会显示每隔 500 毫秒内存的状态（容量、已用内存、外部内存、常驻集大小和 GC）。显示应用程序运行实时的内存状态。

The chart’s x-axis is a timeline of events (timeseries). The data plotted in the y-axis all have a timestamp when the data was collected. In other words, it shows the polled state (capacity, used, external, RSS (resident set size), and GC (garbage collection)) of the memory every 500 ms. This helps give a live appearance on the state of the memory as the application is running.

点击图例按钮会显示采集的测量值和用于显示数据的符号或颜色。

Clicking on the Legend button describes the collected measurements and symbols/colors used to display the data.

Screenshot of a memory anatomy page

Y 轴上 内存大小刻度 会自动调整到当前图表收集的数据范围内。

The Memory Size Scale Y axis scale automatically adjusts to the range of data collected in the current visible chart range.

y 轴上绘制的数据包含：

The quantities plotted on the y-axis are:

Dart/Flutter Heap（Dart/Flutter 堆） 堆中的对象 (Dart/Flutter 对象)。

Dart/Flutter Heap Objects (Dart/Flutter objects) in the heap.

Dart/Flutter Native（Dart/Flutter 原生对象） 不在 Dart/Flutter 堆中，但仍然占用总内存的一部分。该内存中存储了原生对象（例如，文件读取或者图片解码的所占用的内存）。原生对象通过 Dart 嵌入层，从原生操作系统（如 Android、Linux、Windows、iOS）暴露给 Dart VM。嵌入层使用 finalizer 创建一个 Dart 包装类，允许 Dart 代码与这些原生资源通信。 Flutter 有一个用于 Android 和 iOS 的嵌入层。更多信息，参阅服务端应用 Dart 或自定义 Flutter 引擎嵌入层。

Dart/Flutter Native Memory that is not in the Dart/Flutter heap but is still part of the total memory footprint. Objects in this memory would be native objects (for example, from a memory read from a file, or a decoded image). The native objects are exposed to the Dart VM from the native OS (such as Android, Linux, Windows, iOS) using a Dart embedder. The embedder creates a Dart wrapper with a finalizer, allowing Dart code to communicate with these native resources. Flutter has an embedder for Android and iOS. For more information, see Dart on the Server or Custom Flutter Engine Embedders.

Timeline（时间线） 在特定时间点采集的所有内存统计数据和事件的时间戳（时间戳）。

Timeline The timestamps of all collected memory statistics and events at a particular point in time (timestamp).

Raster Cache（光栅缓存） 合成后执行最终渲染时颤振引擎光栅缓存层或图片的光栅缓存大小。详情参阅 Flutter 架构概览和 DevTools 性能视图。

Raster Cache Size of the Flutter engine’s raster cache layer(s) or picture(s) while performing the final rendering after compositing. See Flutter Architectural Overview and DevTools Performance.

Allocated（已分配内存） 堆当前的容量，通常略大于所有堆对象的总大小。

Allocated Current capacity of the heap is typically slightly larger than total size of all heap objects.

RSS - Resident Set Size（常驻集） 常驻集大小显示进程的内存量。包含加载的共享库中的内存，以及所有堆栈和堆内存，不包含交互的内存。

RSS - Resident Set Size The resident set size displays the amount of memory for a process. It doesn’t include memory that is swapped out. It includes memory from shared libraries that are loaded, as well as all stack and heap memory.

有关更多信息，请参阅 Dart 虚拟机结构。

For more information, see Dart VM internals.

Hover card

点击图表会在 X 轴（时间戳）上显示一条垂直黄线，同时显示带有所收集信息的悬浮窗：

Clicking in a chart will display a vertical yellow line where the click occurred on the X-Axis (Timestamp), a hover card will be displayed with the information collected:

Screenshot of the basic memory chart

Memory Events（内存事件） 事件窗口中记录的内存事件，例如虚拟机自动 GC、用户启动的 GC、用户保存的快照、自动快照、分配监控和重置累加数据。

Memory Events Memory Events recorded in the Event Pane e.g., VM GC, User Initiated GC, User Initiated Snapshot, Auto-Snapshot, Allocation Monitoring and, Reset of Accumulators.

Dart / Flutter Memory（Dart / Flutter 内存） 收集的数据容量、已用数据、外部数据、RSS、光栅缓存（图像/图层）。

Dart / Flutter Memory Collected data Capacity, Used, External, RSS, Raster Cache (pictures/layers).

Flutter and User Events（Flutter 和自定义的事件） 扩展事件，例如 Flutter.ImageSizesForFrame，用户自定义事件。参阅事件。

Flutter and User Events Extension events e.g., Flutter.ImageSizesForFrame, user custom events see Events.

顾名思义，集合事件收集了最接近特定时间戳（tick）的所有事件，并将事件显示到 x 轴最近的位置。

Aggregate events, as the name implies, collects all the events nearest a particular timestamp (tick) and displays the events to the x-axis’ closest tick.

如果此时间戳处收集了多个事件，则会显示一个深色三角形，包含事件集合的列表。集合事件收集了最接近特定时间戳 (tick) 的所有事件，并将事件显示到 x 轴最近的位置。展开将显示每个事件的更多信息：

If more than one event, collected at this timestamp, a dark magenta triangle is displayed with the aggregate list of events. The aggregate vents collects all the events nearest a particular timestamp (tick) and displays the events to the X-Axis closest tick. Expanding the events will display the values for each event: Aggregate Events

如果只收集了一个事件，则会显示一个浅色三角形，并显示单个事件信息：

If only one event is collected, a lighter magenta triangle color is displayed with the single event values: Single Events

如果显示 Android 内存图表，则 Android 部分采集的数据将显示在「Dart / Flutter 内存」和「Flutter 和自定义的事件」之间。例如：

If the Android memory chart is displayed then the Android collect data will displayed between the “Dart / Flutter Memory” and the “Flutter and User Events” e.g.,

Hovercard of Android chart is visible

Android 图表

Android chart

当连接到 Android 应用程序时，DevTools 会从 ADB 连接的应用程序摘要中（每 500 毫秒一次）收集 Android 的 ADB（Android 调试通道）内存信息。这部分内存信息非常有趣。如果你从 ADB 工具中采集此信息，它将是这样的：

When connected to an Android app, DevTools collects Android’s ADB (Android Debug Bridge) meminfo from an ADB app summary (polled every 500 ms). This meminfo section is the most interesting at a high-level. If you were to collect this info from the ADB tool, this is what it would look like:

> adb shell dumpsys meminfo io.flutter.demo.gallery -d

 App Summary
                       Pss(KB)
                       -------
           Java Heap:     5192
         Native Heap:    11992
                Code:     2132
               Stack:       60
            Graphics:    53700
       Private Other:    42800
              System:    84493
 
               TOTAL:   200369       TOTAL SWAP PSS:    82168

此图表是应用程序运行时 Android 内存状态的另一个时间序列图。上述值会被绘制到 y 轴上（Java 堆、原生堆、代码大小、堆栈大小、图形堆栈、系统大小和总大小）。

This chart is another timeseries graph of the state of Android memory as the application is running. The quantities plotted on the y-axis are the above values (Java Heap, Native Heap, Code size, Stack size, Graphics stack, System size and total).

点击时间戳（x 位置）将显示该时间段内收集的所有数据点。

Clicking on a timestamp (x-position) will display all data points collected for that time period.

Screenshot of Android Memory Chart

悬浮窗将显示所有采集到的 Android 内存数据。

The hover card will display the values of all collected Android memory data.

Time Time（时间戳）

内存数据的采集时刻 - 请参阅以下的说明。

The timestamp for the current data values collected - see descriptions below.

Total（总计大小）

已使用的总内存大小，由几类不同的内存组成，所有类别都沿着 y 轴绘制，如下所述。

The total memory in use. Total memory is comprised of several different categories, all of which are plotted along the y-axis. These categories are described below.

Other Other（其他）

「其他」使用情况对应于 ADB 的「Private Other（其他私有）」部分，这是系统不确定如何分类的内存。注意：这一部分是「其他」和「系统」（共享和系统内存使用- 对应 ADB 的 System（系统）部分）的组合。

Other memory usage corresponds to the ‘Private Other’ field from ADB. This is memory used by the app that the system isn’t sure how to categorize. Note: The Other trace is a combination of Other and System (shared and system memory usage) - corresponds to ‘System’ field from ADB.

Code Code（代码）

「代码」使用情况对应于 ADB 的「Code（代码）」部分。这是应用程序中静态代码和资源的内存，如 dex 字节码、优化或编译的 dex 代码、.so 库和字体。

Code memory usage corresponds to the ‘Code’ field from ADB. This is memory that your app uses for static code and resources, such as dex byte code, optimized or compiled dex code, .so libraries, and fonts.

Native Heap Native Heap（本地堆）

「本地堆」使用情况对应于 ADB 中的「Native Heap（本地堆）」部分。这是从 C 或 C++ 代码分配的对象的内存。即使你的应用程序中没有使用 C++，也可以看到本地内存的使用，因为 Android 框架使用本地内存来处理各种任务。比如，用来处理图像资源和其他图形，即使你编写的代码是 Java 或 Kotlin。

Native Heap usage corresponds to the ‘Native Heap’ field from ADB. This is memory from objects allocated from C or C++ code. Even if you’re not using C++ in your app, you might see some native memory used here because the Android framework uses native memory to handle various tasks on your behalf. Some examples of these tasks are handling image assets and other graphics—even though the code you’ve written is in Java or Kotlin.

Java Heap Java Heap（Java 堆）

「Java 堆」使用情况对应于 ADB 的「Java Heap（Java 堆）」部分。这是 Java 或 Kotlin 代码分配的对象的内存。

Java Heap usage corresponds to the ‘Java Heap’ field from ADB. This is memory from objects allocated from Java or Kotlin code.

Stack Stack（堆栈）

「堆栈」使用情况对应于 ADB 的「Stack（堆栈）」部分。这是应用程序中本地和 Java 堆栈使用的内存。通常与应用程序正在运行的线程数有关。

Stack usage corresponds to the ‘Stack’ field from ADB. This is memory used by both native and Java stacks in your app. This usually relates to how many threads your app is running.

Graphics Graphics（图形）

「图形」使用情况对应于 ADB 的「Graphics（图形）」部分。这是用于图形缓冲队列在屏幕上显示像素的内存，包括 GL 曲面、GL 纹理等。注意：这是与 CPU 共享的内存，而不是专用的 GPU 内存。

Graphics usage corresponds to the ‘Graphics’ field from ADB. This is memory used for graphics buffer queues to display pixels on the screen, including GL surfaces, GL textures, etc. Note: This is memory shared with the CPU—not dedicated GPU memory.

内存控制

Memory controls

在内存页面顶部的图表上方，有几个按钮和下拉列表，用于控制内存数据的显示方式。

At the top of the memory page, above the charts, are several buttons and dropdowns that control how memory data is displayed.

Screenshot of a memory controls

Pause Pause（暂停）

暂停内存概览图表的变化，可以检查已展示的数据，但仍会接收到传入的内存数据。注意，范围选择器会继续向右增长。

Pause the memory overview chart to allow inspecting the currently plotted data. Incoming memory data is still received; notice the Range selector continues to grow to the right.

Resume Resume（继续）

恢复内存概览图表，使其处于活动状态，显示当前时间和最新内存统计数据。

Resume the memory overview chart so that it is live, displaying the current time and the latest memory statistics.

Clear Clear（清除）

清除内存监控中收集的所有数据。

Clear all collected data from the memory profiler.

Display Display（显示范围）

x 轴的显示区间。例如，将此下拉列表设置为「显示 5 分钟」，则显示最近 5 分钟的内存数据。

The duration of the x-axis. For example, if this dropdown is set to “Display 5 minutes”, memory data from the last 5 minutes will be displayed.

- Display 1 Minute - Display 1 Minute（显示最近 1 分钟）

- Display 5 Minutes - Display 5 Minute（显示最近 5 分钟）

- Display 10 Minutes - Display 10 Minute（显示最近 10 分钟）

- Display All Minutes (slider disabled) - Display All Minutes (slider disabled)（显示所有时间 - 禁用滑动）

Source Source（数据来源）

数据来源可以是「Live Feed」（从连接的 Flutter 应用程序中获取实时数据），也可以是通过点击「导出」创建的本地数据文件。

Source can be either “Live Feed”, which pulls data from the connected Flutter app, or one of the available offline data files, which are created by clicking “Export”.

Android Memory Android Memory（安卓内存）

显示或隐藏 Android 内存图表。

Displays or hides the Android Memory Chart.

GC GC（垃圾回收）

启动垃圾回收 - 压缩堆空间。

Initiates a garbage collection - compaction of the heap.

Export Export（导出）

为事件时间线、内存概览图和 Android 概览图保存已收集的数据。保存的文件显示在「Source（数据来源）」下拉列表中。选择文件将加载数据。

Saves collected data for Event Timeline, Memory Overview Chart and Android Overview Chart. Files saved are displayed under the Source dropdown. Selecting a file loads the offline data.

内存相关操作

Memory actions

内存图表（事件时间线、内存概览和 Android 概览图表）下方有两个 tab, 分别用于分析和收集 DevTools 所连接到的应用程序的内存使用情况。

Below the memory charts (Event Timeline, Memory Overview and Android Overview charts) are interactive actions used to collect and analyze information about memory usage while using the application DevTools is connected to there are two tabs:

Two Tabs Memory Actions

Analysis 选项

Analysis tab

分析选项 会收集由用户手动保存和 DevTools 检测到内存峰值时自动保存的内存快照。每个快照都会被分析并生成分析结果。

The Analysis tab collects memory snapshots both user initiated and auto-collected by DevTools, when DevTools detects memory spikes. Each snapshot is analyzed and an analysis is created too.

Analysis 选项下的操作

Analysis actions

analysis 选项下的操作包括：

The actions available for Analysis are:

Screenshot of a memory actions

Snapshot（快照） 点击 Snapshot 按钮向 Dart VM 发出请求，以保存内存当前的状态。内存对象可以按属性排序，如类名、大小、分配的实例（参见快照类）。

Snapshot Clicking the Snapshot button makes a request to the Dart VM to collect the current state of memory. The memory objects can be sorted by attributes such as class name, size, allocated instances (see Snapshot classes).

Treemap（树形图） 如果 Treemap 开关打开，快照将以树形图的形式在高级视图中显示当前活动的对象、最后一个快照和内存。（详情待定）

Treemap If the Treemap switch is on the snapshot displays currently active memory objects, the last snapshot, memory in a high-level view as a tree map. (TBD details).

Group By（分组方式） 下拉列表选择数据的分组方式，可以按实例或按类名分组。

Group By Dropdown to select how data is grouped, which can either be by instance or by class name.

Collapse All（折叠全部） 折叠树表中的所有节点。

Collapse All Collapse all nodes in the tree table.

Expand All（展开全部） 展开树表中的所有节点。

Expand All Expand all nodes in the tree table

分析和快照视图

Analysis and Snapshots view

所有分析和快照都显示在树表视图中：

All Analyses and Snapshots are displayed in a Table Tree View:

Two Tabs Memory Actions

快照按库分组，在库中按类分组，每个类将显示该类的已知实例列表。

The snapshots are grouped by library and within library by class and each class will display the list of known instances for that class.

快照是特定时间点上所有内存对象的完整视图。在树中导航到类及其实例（调用构造函数创建的实例）。如果实例存在，扩展类将显示所有活动实例（对象）。点击一个类的实例，将在树表的右侧显示内存的检查信息。

A snapshot is a complete view of all memory objects at a particular point in time. Navigating, in the tree, to a class and it’s instances (if the constructor was called to create an instance). If instances exists expanding the class will display all live instances (objects). Clicking on an instance, of a class, will bring up the memory inspector to the right-side of the table tree.

Two Tabs Memory Actions

快照

Snapshots

The Snapshot button

点击 Snapshot（快照） 按钮显示堆的所有活动的类及其实例的当前状态。

Clicking the Snapshot button shows the current state of the heap with regard to all active classes and their instances.

Screenshot of the Snapshot classes

此窗口显示堆中分配的类、类的所有实例并且可以检查某个特定的实例的信息。

This pane shows classes allocated in the heap, all instances for a class, and the ability to inspect a particular instance.

此外，当 DevTools 检测到所用内存出现峰值（内存增长 > 40%）时，会自动生成快照。

In addition, a snapshot can automatically occur when DevTools notices a spike in memory used (growth of > 40%).

每个快照（手动或自动）都将生成快照的分析。例如，可能发生的组映像问题。将来，其他可能引起内存问题的常见 Flutter 编码问题（例如字体、文件、JSON 等）也会加入到分析中。

Every snapshot, manual or automatic, will generate an analysis of the snapshot e.g., groups image problems that might have occurred. In the future, other common Flutter coding issues e.g., Fonts, Files, JSON, etc. that could cause memory problems will be flagged.

Tree View of Memory 内存树视图

树表视图显示关键的内存事件（用户请求的快照、自动快照、快照分析、内存分配监控）。

The tree table view displays outstanding memory events (user requested snapshots, automatic snapshots, snapshot analyses, memory allocation monitoring).

Memory Inspector 内存检查器

根据树状图中当前选定的行显示其分析、快照或监视的内容。

Display either the contents of an analysis, snapshot or monitoring based on the currently selected row in the tree view.

Snapshots have major tree nodes: 快照具有主要的树节点：

External External（外部内存）

不在 Dart 堆中但仍然占用总内存一部分的内存。外部内存中的对象可以是原生对象（例如，文件读取或者图片解码的所占用的内存）。原生对象通过 Dart 嵌入层，从原生操作系统（如 Android、Linux、Windows、iOS）暴露给 Dart VM。嵌入层使用 finalizer 创建一个 Dart 包装类，允许 Dart 代码与这些原生资源通信。 Flutter 有一个用于 Android 和 iOS 的嵌入层。更多信息，参阅服务端应用 Dart 或自定义 Flutter 引擎嵌入层。

Memory that is not in the Dart heap but is still part of the total memory footprint. Objects in external memory would be native objects (for example, from a memory read from a file, or a decoded image). The native objects are exposed to the Dart VM from the native OS (such as Android, Linux, Windows, iOS) using a Dart embedder. The embedder creates a Dart wrapper with a finalizer, allowing Dart code to communicate with these native resources. Flutter has an embedder for Android and iOS. For more information, see Dart on the Server or Custom Flutter Engine Embedders.

Filtered Filtered（筛选）

筛选项中包含了筛选过的包。

Filter are the packages being filtered.

Packages Packages（包）

应用程序使用的用户包和 Src — 空的 Dart 包。

User packages used by the application and Src - the empty Dart package.

上述每个节点下都是类节点，是分配给该类的对象的集合。点击类名将显示该类的所有实例。单击某个实例将显示其检查信息（字段和值）。

Under each of the above nodes are class nodes, an aggregate of the objects allocated to this class. Clicking a class name displays a list of class instances. and under each class are all the instances of a class. Clicking on an instance will inspect the contents of that instances (fields and values).

检查快照中的类实例

Inspecting a class instance in a snapshot

展开类将显示该类的活动的实例。点击某个特定实例将显示该实例字段的类型和值。

Expanding a class displays the active instances for that class. Clicking on an particular instance displays the type and value of the fields for that instance.

Screenshot of the inspecting an instance

快照分析

Analysis of a snapshot

每个快照都会在分析节点下创建相应的分析内容（分析的时间对应快照的生成时间）。

Every snapshot creates a corresponding Analyzed entry under the Analysis node (the Analyzed date/time corresponds to the matching Snapshot date/time).

Screenshot of a Snapshot Analysis

目前，分析查找图片的常见问题。例如，加载大文件而不是缩放的缩略图，没使用 ListBuilder 管理列表中的图片等。

Currently, Analysis looks for common problems with images e.g., loading large files instead of scaled thumbnails, not using a ListBuilder to manage images in a list, etc.

该分析从快照中提取所有与图片相关的类和实例，并将数据组织在一个位置。这样我们不必搜索和了解哪些类与图片相关，并检查其实例。

The Analysis pulls all Image related classes and instances from a snapshot and organizes the data in one place instead of having to search for the all the classes and inspect the instances to understand what are just image related classes.

在上图的分析中，原始图片位于外部内存的 _Int32List（或较新手机的 _Int64List）部分，根据实例大小分类到 Buckets 中。可以看出，图片大小为 10K-50K 的有 11 张，10M-50M 有 1 张，1M-10M 有 7 张，大于 50M 的有 4 张。这个应用程序中共有超过 500M 的图片在手机上渲染为小图。

In the above Analysis the raw images are located in the Externals portion of memory _Int32List (or _Int64List for newer phones) organizes the instances sizes into buckets. Eleven images are 10K-50K, one image is 10M-50M, seven images are 1M-10M and four images are greater than 50M. For a grand total of over 500M of this app constitute images rendered as small images on a phone.

Allocation 选项

Allocation tab

Allocation 选项可以监控所有类的实例，报告分配的对象数和所有对象消耗的字节数。数字以绝对总数和累计总数显示。一开始，累计数据（对象数量和字节大小）等于第一次发起监控请求时的初始总数。可以随时将累计数据重置为零，这样下次监控请求将返回自上次重置以来的累计值。

The Allocation tab allows monitoring the instances of all classes, reporting the number of objects allocated and number of bytes consumed by all objects. The numbers are displayed in absolute totals as well as accumulated totals. Initially, the accumulated values (number of objects and size in bytes) are equal to the initial totals at the time of the first monitor request. The accumulators can be reset, to zero, at any time such that the next monitor request will return the accumlated values since the last reset.

此外，一小组类可以跟踪类的每个实例的内存分配。调用构造函数时，监控器可以捕获到对应的堆栈。但跟踪这些分配性能代价很大（缓慢的），因此不要频繁使用跟踪。

Additionally, a small set of classes can track the allocation of each instance of a class. The tracking captures a stack trace when the constructor was called. The overhead to track these allocations are expensive (slow) therefore tracking should be used sparingly.

Allocation actions

Screenshot of a memory actions

Track Track（跟踪）

记录和监控所有实例的数量和大小（以字节为单位）。点击「Track（跟踪）」按钮，实例分配数据会显示在下方的表格中。对于表中的每个实例，「Delta（增加量）」列表示自上次重置数据以来内存的分配大小。

Records and monitors the number of instances and size of all instances in bytes. Clicking the “Track” button, a table will populate with instance allocation data. For each instance in the allocation table, The “Delta” column reflects the number of memory allocations since the last reset.

Reset Reset（重置）

重置表中每个实例的累计数据（增加量列）。下次按下「Monitor（监控）」按钮时，增加量列将显示自上次重置以来新分配的实例和所占空间。

Resets the accumulator counts (Delta columns) for each instance in the allocation table. The next time the “Monitor” button is pressed, the “Delta” columns displays the populate with the new instances and sizes since the last reset.

Search Search（搜索）

搜索功能会存在实例分配数据时可用。输入或从下拉列表中选择名称将跳转到表中对应的类。

The search field is enabled when the instance allocation data exists. Typing, or selecting a name from the dropdown, will navigate to that class name in the table.

Filter Filter（筛选）

弹出一个包含所有已展示的库和类名的对话框（已选中）。

Display a dialog box of libraries and class names to display (checked on).

分配视图

Allocation view

已连接的应用程序中所有可用的类的分配信息会显示表中：

Allocations are displayed in a table view of each class available to the connected application:

Two Tabs Memory Actions

每行显示类名、实例数和对应分配的增加（自上次重置以来的累计数据）的字节数。

Each row displays the class name the number of instances and bytes allocated with deltas (accumulators since last reset).

Track with Stack Trace Track with Stack Trace（堆栈跟踪）

如果启用，则在调用类构造函数创建实例时记录堆栈。

If enabled records the stack trace when the instance is created, class constructor called.

Class Name Class Name（类名）

监控的类名

Class allocations monitored.

Total Instances Total Instances（实例总计数量）

类活动实例总数。

Total number of active instances for the class.

Delta Instances Delta Instances（实例的增加数量）

由重置按钮控制的实例累计数据。当按下「Reset（重置）」时，累计数据重置为零，然后每次按下「Track（跟踪）」按钮时，当前总计和增加数量都会更新。

An accumulator of change in instance count controlled by the Reset button. When Reset is pressed the accumulators rest to zero then each time the Track button is pressed the current totals and deltas are updated.

Total Bytes Total Bytes（总字节数）

为类的所有实例分配的总字节数。

Total number of bytes allocated of all instances for the class.

Delta Bytes Delta Bytes（增加的字节数）

由重置按钮控制的实例字节变化累计数据。当按下「Reset（重置）」时，累计数据重置为零，然后每次按下「Track（跟踪）」按钮时，当前总计和增加数量都会更新。

An accumulator of change in instance bytes created controlled by the Reset button. When Reset is pressed the accumulators rest to zero then each time the Track button is pressed the current totals and deltas are updated.

Timestamp of Last Track Timestamp of Last Track（上一次启用跟踪的时间）

按下「Track（跟踪）」按钮的时间。

The time when the Track button was pressed.

Change Bubble Change Bubble（更改气泡）

小气泡，表示已经在表中记录并更新的更改。

Small bubble to indicate the changes collected have been collected and updated in the table.

更多信息，请参阅分配跟踪。

For more information see Allocation Tracking.

管理堆中的对象和统计数据（分配监控）

Managing the objects and statistics in the heap (Monitor Allocations)

The Monitor Allocations button

点击「Track（跟踪）」按钮可以监控类分配的实例总数和字节总数。此外，为实例的分配维护两个累计数据（总计数量和增加数量），用户可以通过操作（按下重置按钮）重置为零。该机制对于查找内存泄漏非常有用。

Clicking the allocation Track button monitors the total number of instances and total number of bytes allocated for a class. In addition, two accumulators are maintained for instances and bytes allocated these accumulators can be reset, to zero, by user action (pressing the Reset Accumulators button). The mechanism is useful to find memory leaks.

Reset Accumulators button

按下 Reset（重置） 按钮时，所有类别的累计数据都会重置为零。当发生重置时，事件时间线上会出现「监控重置」事件。再次点击 Reset（重置） 按钮将两个累计数据重置为零。

When the Reset button is pressed, the accumulators for all classes resets to zero. When reset is occurs a “monitor reset” event to the Event Timeline. Clicking the Reset button again resets both accumulators to zero.

Classes Classes（类）

堆中的活动的类。

Active classes in the heap.

Instances column Instances column（实例列）

堆中所有类的活动对象（实例）总数

Total active objects (instances) for all classes in the heap

Delta column Delta column（数量增加列）

自上次按下「Reset（重置）」后所有实例的累计数量。点击重置按钮重置类实例的累计数量。这对于查找内存泄漏非常有用。

Accumulator counts of all instances since last “Reset” was pressed. Clicking the Reset button initializes the accumulated (Delta) instances of a class. This is useful for finding memory leaks.

Bytes column Bytes column（字节列）

堆中类的所有实例的总字节数。

Total bytes consumed for all instances of a class in the heap.

Delta column Delta column（字节增加列）

自上次按下「Reset（重置）」后所有实例的累计字节数。点击重置按钮重置类实例的累计字节数。这对于查找内存泄漏非常有用。

Accumulator counts bytes allocated since last “Reset” was pressed. Clicking the Reset button initializes the accumulated (Delta) bytes for all instances of a class. This is useful for finding memory leaks.

分配跟踪

Allocation tracking

除了跟踪一个类的所有实例的对象数和字节数外，还可以在调用类的构造函数时记录堆栈，来帮助缩小分配可能出错的范围。为此，请选中类的跟踪复选框，例如：

In addition to tracking the number of objects and bytes consumed for all instances of a class, a stack trace can be recorded when a class’s constructor is called to help narrow where allocations might be astray. To do this enable the Track checkbox for a class e.g.,

Enable Stack Trace Tracking

在你与应用程序交互，想要查看实例分配时，再次按下「Track（跟踪）」按钮。这将更新正在跟踪的实例的数量，例如下图中的 118。展开跟踪的实例将显示所有实例以及创建每个实例的时间，例如：

Interact with your application then when you want to view the instances allocation press the “Track” button again. This will update the count for the instances being tracked e.g., 118 in the below figure. Expanding the instances tracked will display all the instances and timestamp when each instance was created e.g.,

Class Tracking

选择实例将显示调用类的构造函数（已分配）时的堆栈，例如：

Selecting an instance will display the call stack at the time the class’s constructor (allocated) was called e.g.,

Call Stack

筛选、搜索和自动补全

Filtering, Searching and Auto-Complete

「Analysis（分析）」和「Allocations（分配）」选项都支持搜索和筛选。输入要查找的类的名称，例如，ObectWithUniqueId 将返回与与输入字符匹配的列表。列表中的第一项高亮显示。

Both the Analysis and Allocations tabs support searching and filtering Begin typing in the name of the class you’d like to find e.g., ObectWithUniqueId will return a list that matches the characters typed so far. The first item in the list is highlighted.

当自动补全可见时，按下按键：

Pressing a keystroke when auto-complete is visible:

ENTER

选择高亮显示的行（GlobalObjectKey）跳转到当前树表视图（快照）或表（分配）中该类名对应的行。

Selects the highlighted line (GlobalObjectKey) and navigates to the row with that class name in the active tree table (Snapshot) or table (Allocations).

UP/DOWN arrows 上/下箭头

在可能匹配的列表中跳转，突出显示列表中的下一项。

Rotates through the list of possible matches highlighting the next item in the list.

ESCAPE

清除并取消所有搜索。

Clears and cancels all searching.

Searching

输入更多字符来缩小类名范围，例如键入 Obje 显示：

Typing more characters would narrow down the possible class names e.g., typing Obje displays:

Narrower Search

最后，输入 ObjectW 显示精确匹配：

Finally, typing ObjectW displays the exact match:

Narrowed Search

筛选

Filtering

筛选用于将库和类从主列表（表）移动到筛选组，帮助减少在分析内存时不太重要的可见类的数量。

Filtering is used to move libraries and classes from the main list (tables) to a Filter group to help reduce the number of classes visible that are less important while profiling memory.

Filtering

Hide Private Classes Hide Private Classes（隐藏私有类）

前缀带有下划线类的类。

Class names prefix with an underscore.

Hide Classes with No Instances Hide Classes with No Instances（隐藏没有实例的类）

从未构造的类将被过滤。

Classes never constructed are filtered.

Hide Libraries with No Instances Hide Libraries with No Instances（隐藏没有实例的库）

库中所有类都从未被实例化过，将会被隐藏

All classes in a library never constructed the library is filtered.

Hide Libraries or Packages Hide Libraries or Packages（隐藏库或包）

显示应用程序中使用的所有库的列表。默认情况下启用，系统相关库将被过滤掉（例如：dart:、package:flutter）。如果你对 Dart 核心库和类或 Flutter 框架感兴趣，可以关闭自动过滤掉的库。

List of all libraries used in your application are displayed. By default the libraries enabled above are filtered out (dart:, package:flutter, etc.). The libraries automatically filtered can be enabled if you are interested in Dart core libraries and classes or the Flutter framework.

设置

Setting

内存分析有一个特定的设置对话框：

The Memory profiler has a specific settings dialog:

Settings

Collect Android Memory Statistics using ADB Collect Android Memory Statistics using ADB（使用 ADB 收集 Android 内存统计信息）

默认情况下，如果 DevTools 通过 Android 设备 / 模拟器连接到应用程序，则不会收集 Android 内存统计信息。使用 ADB 收集开销很大，并且可能会隐藏应用程序中的性能问题。

By default if DevTools is connected to your application via an Android device/emulator then Android memory statistics are not collected. Collecting with ADB can be expensive and may hide performance issues in your app.

Display Data in Units (B, K, MB, GB) Display Data in Units (B, K, MB, GB)（以单位（B、K、MB、GB）显示数据）

默认情况下，悬浮窗中显示的数据使用单位而不是原始值。关闭此选项将显示原始数字，例如 125M 将显示为 125235712。

By default data displayed in the hover card are scaled using units instead of raw values. Turning off this will display the raw numbers e.g., 125M would display as 125,235,712.

Enable advanced memory settings Enable advanced memory settings（启用高级内存设置）

如果启用，将显示 GC 按钮，请求虚拟机（手动）垃圾收集内存。此手动 GC 只是对虚拟机的请求。虚拟机可能不压缩、部分压缩或完全压缩堆。

If enabled, the GC button is displayed to ask the VM to garbage collect memory (manually). This manual GC is only a request to the VM. The VM may decide to do no compaction, some compaction or complete compaction of the heap.

内存问题案例学习

Memory problem case study

使用大量网络图片导致内存泄漏的学习，以及有关使用 DevTools 内存分析器、检测内存问题和修复问题的分步说明，请参阅案例研究。

Memory leak study using large network images was added with step-by-step instructions on using DevTools Memory profiler, detecting the memory problem and fixing the problem, see case study.

虚拟机术语表

Glossary of VM terms

以下是一些计算机科学概念，它们将帮助你更好地理解应用程序如何使用内存。

Here are some computer science concepts that will help you better understand how your application uses memory.

Garbage collection (GC) Garbage collection (垃圾回收)

GC 是搜索堆以定位和回收应用程序不再使用的内存区域的过程。这个过程允许重新使用内存，将应用程序由于内存不足导致的崩溃风险降至最低。 GC 由 Dart VM 自动执行。在 DevTools 中，你可以通过点击 GC 按钮按需执行垃圾回收。

GC is the process of searching the heap to locate, and reclaim, regions of “dead” memory—memory that is no longer being used by an application. This process allows the memory to be re-used and minimizes the risk of an application running out of memory, causing it to crash. Garbage collection is performed automatically by the Dart VM. In DevTools, you can perform garbage collection on demand by clicking the GC button.

Heap Heap（堆）

动态分配的 Dart 对象存在于称为堆的内存部分中。当没有任何对象指向它，或者当应用程序退出时。在堆中分配的对象将被回收（符合 GC 的条件）。当没有任何东西指向某个对象时，它不处于存活状态。当一个对象被另一个对象指向时，它是存活的。

Dart objects that are dynamically allocated live in a portion of memory called the heap. An object allocated from the heap is freed (eligible for garbage collection) when nothing points to it, or when the application terminates. When nothing points to an object, it is considered to be dead. When an object is pointed to by another object, it is live.

Isolates

Dart 通过 Isolates 的方式支持并发，你可以认为这样的过程没有开销。每个 Isolates 都有自己的内存和代码，不受任何其他 Isolates 的影响。更多信息，请参见事件循环和 Dart。

Dart supports concurrent execution by way of isolates, which you can think of processes without the overhead. Each isolate has its own memory and code that can’t be affected by any other isolate. For more information, see The Event Loop and Dart.

Memory leak Memory leak（内存泄漏）

当一个对象处于存活状态（意味着有其它对象指向它），但它没有被使用时（因此它不应该有来自其他任何对象的引用），就会发生内存泄漏。这样的对象不能被垃圾收集，因此它会占用堆中的空间并导致内存碎片。内存泄漏会给虚拟机带来不必要的压力，并且可能很难调试。

A memory leak occurs when an object is live (meaning that another object points to it), but it is not being used (so it shouldn’t have any references from other objects). Such an object can’t be garbage collected, so it takes up space in the heap and contributes to memory fragmentation. Memory leaks put unnecessary pressure on the VM and can be difficult to debug.

Virtual machine (VM) Virtual machine (虚拟机)

Dart 虚拟机是一种直接执行 Dart 代码的软件。

The Dart virtual machine is a piece of software that directly executes Dart code.

使用性能视图 (Performance view)

它是什么?
What is it?
Flutter frames chart
时间线事件表
Timeline events chart
CPU 分析器
CPU Profiler
导入导出
Import and export

它是什么?

What is it?

性能视图提供了应用活动的时间线以及性能信息。它由三个部分组成，且每个部分的粒度都更加细。

The performance view offers timing and performance information for activity in your application. It consists of three parts, each increasing in granularity.

Flutter 火焰图（仅支持 Flutter 应用）
Flutter frames chart (Flutter apps only)
时间线事件图
Timeline events chart
CPU 监控
CPU profiler

Flutter frames chart

Screenshot from a performance snapshot

Selecting a bar from this chart centers the flame chart below on the timeline events corresponding to the selected Flutter frame. The events are highlighted with blue brackets.

Screenshot from a timeline recording

UI

UI 线程执行 Dart VM 中的 Dart 代码。它包括你的应用程序和 Flutter 框架的所有代码。当你创建或打开一个页面， UI 线程会创建一个图层树和一个轻量级的与设备无关的绘制指令集，并把图层树交给设备的 raster（栅格）线程进行渲染。不要阻塞这个线程。

栅格线程

Raster

栅格化线程（也就是我们之前知道的 GPU 线程）执行 Flutter 引擎中图形相关的代码。这个线程通过与 GPU (图形处理单元) 通信，获取图形树并显示它。你不能直接访问 Raster 线程或它的数据，但如果这个线程较慢，那它肯定是由你的 Dart 代码引起的。图形化库 Skia 运行在这个线程上，有时候也称它为光栅线程。

有时候一个页面的图形层树比较容易构建但 raster 线程的渲染却比较昂贵。在这种情形下，你需要找出导致渲染变慢的代码。为 GPU 设定特定多种类型的 workload 是相当困难的。在一些特定的情形下，多个对象的透明度重叠、剪切或阴影，有可能会导致不必要的 saveLayer() 的调用。

更多详细信息，请查看文档定位 GPU 图表中的问题。

For more information on profiling, see Identifying problems in the GPU graph.

丢帧 (Jank)

Jank

帧渲染图表使用红色图层显示帧延时。如果一帧的渲染时间超过 16ms，则会被认为此帧是延时的，为了达到帧渲染频率到 60 FPS (每秒帧数)，每一帧的渲染时间必须等于或少于 16 ms。如果没有达到这个目标，你会发现 UI 不流畅或丢帧。

更多关于性能分析信息，请查看文档：Flutter 性能分析。

For more information on how to analyze your app’s performance, see Flutter performance profiling.

时间线事件表

Timeline events chart

Screenshot of timeline events for a frame

The flame chart supports zooming and panning:

To zoom, scroll up and down with the mouse wheel / trackpad
To pan horizontally, either click and drag the chart or scroll horizontally with the mouse wheel / trackpad
To pan vertically, either click and drag the chart or use alt + scroll
The WASD keys also work for controlling zoom and horizontal scroll position

火焰图表支持缩放和平移。上下滚动分别进行放大和缩小。你可以通过单击和拖拽图表或水平滚动的方式来移动它。在下一节的描述中，你会了解在 CPU 分析器中单击一个事件来查看 CPU 信息。

You can click an event to view CPU profiling information in the CPU profiler below, described in the next section.

CPU 分析器

CPU Profiler

单击 Record 开始进行记录 CPU 信息，完成后点击 Stop 停止记录，C PU 分析器会把收集的信息推送到VM并分别在不同的信息窗口进行展示调用树 (Call Tree, Bottom Up, and Flame Chart).

分析粒度

Profile granularity

VM 收集 CPU 样本的默认速率为 1/250μs (即每 250 微秒收集一次数据)。一般情况下，Profile granularity 的默认值为 “medium”。可以通过页面顶部下拉列表进行修改。抽样率低、中、高粒度分别顺序对应 1/50μs、1/250μs 和 1/1000μs。正确设定此值对性能分析非常重要。

高粒度 的配置会具有更高效的采样率，因此单元时间内采集的 CPU 信息会更加详细且采集样例更多。因些 VM 会被经常中断以收集样本数据，所以这有可能会影响你的应用程序的运行或导致性能下降。 VM 中 CPU 样例数据信息的存储空间是受限制的，所以也会导致 VM 的 CPU 示例缓冲区很快地填充满且会产生溢出。相对低采样率，高采样率存储空间会被迅速填满并会出现溢出。一旦空间溢出，就有可能导致采样数据丢失。

低粒度 的配置具有较低的采样率，因此单元时间内采集的 CPU 信息会比较粗略且采集样例较少。当然，这样也会对你的应用程序性能影响更小。 VM 示例缓冲区填充速度也会较慢，因此你可以采集到相当长一段时间内应用程序的 CPU 样例数据，这也意味着你有更好的机会去查看 CPU 样例数据。

火焰图表

Flame chart

火焰图选项卡主要用于显示一段持续时间内 CPU 的样本信息。图表展示的是自上而下的调用堆栈信息，即上面的堆栈帧调用下面的堆栈帧。每一个堆栈帧的宽度代表 CPU 执行的时长。栈帧消耗 CPU 的时间越长，就越洽有可能是我们进行性能改进的好地方。

Screenshot of a flame chart

调用树 (也叫跟踪树)

Call tree

调用树视图是一种自上而下展示 CPU 中的调用堆栈信息方法。在下图中的表格中可以看出，展开其中的一个方法可以查看它所有的 调用者。

The call tree view shows the method trace for the CPU profile. This table is a top-down representation of the profile, meaning that a method can be expanded to show its callees.

总时间Total time: 此方法运行的总时间，包括了调用者的执行时间(即调用此方法整个的生命周期时长)。Time the method spent executing its own code as well as the code for its callees.
自执行时间Self time: 仅表示执行当前方法把花费的时长。Time the method spent executing only its own code.
方法Method: 调用的方法名称。Name of the called method.
源码Source: 方法所在的文件路径。File path for the method call site.

Screenshot of a call tree table

自下而上

Bottom up

自下而上 视图也是用于显示方法调用堆栈，但顾名思义，它是一个自下而上的表示方式。这意味着表格中的每个最上方的方法实际上是给定 CPU 样本的调用堆栈中的最后一个方法 (换句话说，这是样本的叶节点)。

在这张表中，可以展开一个方法查看它的所有 调用者。

In this table, a method can be expanded to show its callers.

总时间Total time: 此方法运行的总时间，包括了调用者的执行时间(即调用此方法整个的生命周期时长)。Time the method spent executing its own code as well as the code for its callee.
自执行时间Self time: 在自下而上调用树中对于最顶层的方法（叶堆栈帧），它表示执行自己的代码所需要的时间。对于子节点(调用者)，它表示调用者运行被调用者的时间。在下面的这个例子中，调用者 `createRenderObject` 的执行时间等于被调用者 `debugCheckHasDirectionality` 的执行时间。For top-level methods in the bottom-up tree (leaf stack frames in the profile), this is the time the method spent executing only its own code. For sub nodes (the callers in the CPU profile), this is the self time of the callee when being called by the caller. In the following example, the self time of the caller `createRenderObject` is equal to the self time of the callee `debugCheckHasDirectionality` when being called by the caller.
方法Method: 调用方法的名称。Name of the called method.
源码Source: 方法所在的文件路径。File path for the method call site.

Screenshot of a bottom up table

导入导出

Import and export

DevTools 支持导入和导出时间线快照。单击 export 按钮 (帧渲染图表右上角) 下载当前时间线的快照。要导入时间线快照，可以从任何页面拖放快照到 DevTools。提示 : DevTools 仅支持导入 DevTools 导出的源文件。

使用 CPU 探测视图

它是什么？
What is it?
CPU 分析器
CPU Profiler

它是什么？

What is it?

CPU 探测视图能够测量并记录你的 Dart 或 Flutter 应用的片段。

The CPU profiler view allows you to record and profile a session from your Dart or Flutter application.

CPU 分析器

CPU Profiler

分析粒度

Profile granularity

火焰图表

Flame chart

Screenshot of a flame chart

调用树 (也叫跟踪树)

Call tree

调用树视图是一种自上而下展示 CPU 中的调用堆栈信息方法。在下图中的表格中可以看出，展开其中的一个方法可以查看它所有的 调用者。

The call tree view shows the method trace for the CPU profile. This table is a top-down representation of the profile, meaning that a method can be expanded to show its callees.

总时间Total time: 此方法运行的总时间，包括了调用者的执行时间(即调用此方法整个的生命周期时长)。Time the method spent executing its own code as well as the code for its callees.
自执行时间Self time: 仅表示执行当前方法把花费的时长。Time the method spent executing only its own code.
方法Method: 调用的方法名称。Name of the called method.
源码Source: 方法所在的文件路径。File path for the method call site.

Screenshot of a call tree table

自下而上

Bottom up

在这张表中，可以展开一个方法查看它的所有 调用者。

In this table, a method can be expanded to show its callers.

总时间Total time: 此方法运行的总时间，包括了调用者的执行时间(即调用此方法整个的生命周期时长)。Time the method spent executing its own code as well as the code for its callee.
自执行时间Self time: 在自下而上调用树中对于最顶层的方法（叶堆栈帧），它表示执行自己的代码所需要的时间。对于子节点(调用者)，它表示调用者运行被调用者的时间。在下面的这个例子中，调用者 `createRenderObject` 的执行时间等于被调用者 `debugCheckHasDirectionality` 的执行时间。For top-level methods in the bottom-up tree (leaf stack frames in the profile), this is the time the method spent executing only its own code. For sub nodes (the callers in the CPU profile), this is the self time of the callee when being called by the caller. In the following example, the self time of the caller `createRenderObject` is equal to the self time of the callee `debugCheckHasDirectionality` when being called by the caller.
方法Method: 调用方法的名称。Name of the called method.
源码Source: 方法所在的文件路径。File path for the method call site.

Screenshot of a bottom up table

使用网络视图 (Network View)

What is it?
How to use it
- Search and filtering
Other resources

What is it?

The network view allows you to inspect HTTP, HTTPS, and web socket traffic from your Dart or Flutter application.

Screenshot of the network screen

How to use it

Network traffic should be recording by default when you open the Network page. If it is not, click the Record network traffic button in the upper left to begin polling.

Select a network request from the table (left) to view details (right). You can inspect general and timing information about the request, as well as the content of response and request headers and bodies.

Search and filtering

You can use the search and filter controls to find a specific request or filter requests out of the request table.

To apply a filter, press the filter button (right of the search bar). You will see a filter dialog pop up:

Screenshot of the network screen

The filter query syntax is described in the dialog. You can filter network requests by the following keys:

method, m: this filter corresponds to the value in the “Method” column
status, s: this filter corresponds to the value in the “Status” column
type, t: this filter corresponds to the value in the “Type” column

Any text that is not paired with an available filter key will be queried against all categories (method, uri, status, type).

Example filter queries:

my-endpoint m:get t:json s:200

https s:404

Other resources

HTTP and HTTPs requests are also surfaced in the Timeline as asynchronous timeline events. Viewing network activity in the timeline can be useful if you want to see how HTTP traffic aligns with other events happening in your app or in the Flutter framework.

使用调试器工具

开始使用
Getting started
设置断点
Setting breakpoints
调用栈和变量区
The call stack and variable areas
单步调试源码
Stepping through source code
命令行输出
Console output
异常跳出
Breaking on exceptions
已知问题
Known issues
其他资源
Other resources

开始使用

Getting started

开发工具中包含了一个完整的源码级调试器，支持断点、单步调试以及变量检视。

DevTools includes a full source-level debugger, supporting breakpoints, stepping, and variable inspection.

When you open the debugger tab, you should see the source for the main entry-point for your app loaded in the debugger.

In order to browse around more of your application sources, click Libraries (top right) or use the hot key command ⌘ + P / ctrl + P. This will open the libraries window and allow you to search for other source files.

Screenshot of the debugger tab

设置断点

Setting breakpoints

可以点击源码区左边空白（行数展示栏内）来设置断点。单击一次就设置了一个断点，并且也会在 Breakpoints 区域展示出来。再次单击则取消断点。

To set a breakpoint, click the left margin (the line number ruler) in the source area. Clicking once sets a breakpoint, which should also show up in the Breakpoints area on the left. Clicking again removes the breakpoint.

调用栈和变量区

The call stack and variable areas

当应用运行到某个断点时，就会在此处暂停，调试器也会在源码区显示当前暂停的位置。此外，Call stack 和 Variables 区域也会显示暂停时的调用栈以及选中帧的本地变量。在 Call stack 选择其他的帧可以改变变量区的内容。

When your application encounters a breakpoint, it pauses there, and the DevTools debugger shows the paused execution location in the source area. In addition, the Call stack and Variables areas populate with the current call stack for the paused isolate, and the local variables for the selected frame. Selecting other frames in the Call stack area changes the contents of the variables.

在 Variables 内，可以通过点击对象展开查看其内容来检视独立的对象。指针停在 Variables 区域的对象上时会调用该对象的 toString() 方法并展示结果。

Within the Variables area, you can inspect individual objects by toggling them open to see their fields. Hovering over an object in the Variables area calls toString() for that object and displays the result.

单步调试源码

Stepping through source code

三个单步调试按钮在暂停后会变为可用状态。

When paused, the three stepping buttons become active.

使用 Step in 来进入被调用的方法，在遇到方法内的第一行可执行代码时结束。
Use Step in to step into a method invocation, stopping at the first executable line in that invoked method.
使用 Step over 直接执行某个方法调用而不进入内部；该按钮在当前方法内按行执行。
Use Step over to step over a method invocation; this steps through source lines in the current method.
使用 Step out 来跳出当前方法，这种方式会直接执行完所有当前方法内的语句。
Use Step out to step out of the current method, without stopping at any intermediary lines.

另外，Resume 按钮的作用是恢复应用的正常执行。

In addition, the Resume button continues regular execution of the application.

命令行输出

Console output

运行中应用的命令行输出（stdout 和 stderr）会在命令行中输出，该区域在源代码区下方。Logging view 中也可以看到相应输出。

Console output for the running app (stdout and stderr) is displayed in the console, below the source code area. You can also see the output in the Logging view.

异常跳出

Breaking on exceptions

请在调试器视图顶部切换 Ignore 下拉菜单来适配异常跳出的行为。

To adjust the stop-on-exceptions behavior, toggle the Ignore dropdown at the top of the debugger view.

Break on unhandled exceptions：只在断点被认为应用内代码无法捕获时暂停执行。 Breaking on all exceptions：无论是否被捕获都会暂停执行。

Breaking on unhandled excepts only pauses execution if the breakpoint is considered uncaught by the application code. Breaking on all exceptions causes the debugger to pause whether or not the breakpoint was caught by application code.

已知问题

Known issues

当 Flutter 应用执行热重载时，用户的断点会被清除。

When performing a hot restart for a Flutter application, user breakpoints are cleared.

其他资源

Other resources

访问 Debugging 页面来获取更多关于调试器和性能分析的信息。

For more information on debugging and profiling, see the Debugging page.

使用日志视图 (Logging view)

简介
What is it?
标准日志事件
Standard logging events
应用日志
Logging from your application
清理日志
Clearing logs

简介

What is it?

日志视图展示 Dart 运行时和应用框架（比如 Flutter）的事件，以及应用级日志。

The logging view displays events from the Dart runtime, application frameworks (like Flutter), and application-level logging events.

标准日志事件

Standard logging events

默认情况下，日志视图会展示：

By default, the logging view shows:

Dart 运行时的垃圾回收事件
Garbage collection events from the Dart runtime
Flutter 框架事件，比如创建帧的事件
Flutter framework events, like frame creation events
应用的 stdout 和 stderr 输出
stdout and stderr from applications
应用的自定义日志事件
Custom logging events from applications

日志视图的截图

应用日志

Logging from your application

要在代码中输出日志，请查看添加输出代码的方式调试 Flutter 应用页面的日志部分。

To implement logging in your code, see the Logging section in the Debugging Flutter apps programmatically page.

清理日志

Clearing logs

要清理日志视图的日志记录，请点击 Clear logs（清理日志）按钮。

To clear the log entries in the logging view, click the Clear logs button.

使用应用体积工具

这是什么?
What is it?
- 什么是“体积信息”？
  What is “size information”?
- Dart 体积信息
  Dart size information
如何使用
How to use it
分析标签页
Analysis tab
差异标签页
Diff tab
- 读取体积文件
  Loading size files
- 树状图和表格
  Treemap and table
生成尺寸文件
Generating size files

这是什么?

What is it?

应用程序体积工具可让您分析应用的总体积。您可以使用 Analysis 标签来查看「体积信息」的单个快照，或使用 Diff 标签比较使用「体积信息」的两个不同快照。

The app size tool allows you to analyze the total size of your app. You can view a single snapshot of “size information” using the Analysis tab, or compare two different snapshots of “size information” using the Diff tab.

什么是“体积信息”？

What is “size information”?

「体积信息」包含 Dart 代码、原生代码和非代码部分（比如应用包，资源和字体）。一个「体积信息」文件包含您应用的所有图片数据。

“Size information” contains size data for Dart code, native code, and non-code elements of your app, like the application package, assets and fonts. A “size information” file contains data for the total picture of your application size.

Dart 体积信息

Dart size information

Dart AOT 编译器会在编译应用程序时对代码进行摇树优化（仅限 profile 或 release 模式 - AOT 编译器不用于 debug 生成，debug 模式是 JIT 编译的）。这意味着，编译器会尝试删除未使用或无法访问的代码，对应用体积进行优化。

The Dart AOT compiler performs tree-shaking on your code when compiling your application (profile or release mode only—the AOT compiler is not used for debug builds, which are JIT compiled). This means that the compiler attempts to optimize your app’s size by removing pieces of code that are unused or unreachable.

当编译器尽全力优化您的代码后，产出的二进制文件会包含依赖、库、类和函数的集合，以及他们的体积（以字节为单位）。这是我们可以在应用体积工具中分析的 Dart 部分的「体积信息」, 有了这些信息，我们便可以进一步优化 Dart 代码，并且跟踪体积问题。

After the compiler optimizes your code as much as it can, the end result can be summarized as the collection of packages, libraries, classes, and functions that exist in the binary output, along with their size in bytes. This is the Dart portion of “size information” we can analyze in the app size tool to further optimize Dart code and track down size issues.

如何使用

How to use it

如果 DevTools 已经连接到了一个正在运行的应用，点击 “App Size” 标签。

If DevTools is already connected to a running application, navigate to the “App Size” tab.

Screenshot of app size tab

如果 DevTools 未连接到应用，您可以从启动 DevTools 后出现的登录页访问该工具（查看安装说明）。

If DevTools is not connected to a running application, you can access the tool from the landing page that appears once you have launched DevTools (see installation instructions).

Screenshot of app size access on landing page

分析标签页

Analysis tab

「分析」标签页允许您检查体积信息的单个快照。您可以看到层次结构的树状图和表格，并且可以使用 “dominator tree” 和 “call graph” 看到代码的属性数据（例如：为什么编译后的应用程序中包含一段代码）。

The analysis tab allows you to inspect a single snapshot of size information. You can view the hierarchical structure of the size data using the treemap and table, and you can view code attribution data (for example, why a piece of code is included in your compiled application) using the dominator tree and call graph.

Screenshot of app size analysis

读取一个体积文件

Loading a size file

当您打开分析标签页时，您可以看到加载一个体积文件的使用说明。拖动一个尺寸文件到弹框中，并点击 “Analyze Size”。

When you open the Analysis tab, you’ll see instructions to load an app size file. Drag and drop an app size file into the dialog, and click “Analyze Size”.

Screenshot of app size analysis loading screen

查看生成体积文件可以得到有关生成尺寸文件的信息。

See Generating size files below for information on generating size files.

树状图和表格

Treemap and table

树状图和表格可以查看您的应用体积的结构化数据。

The treemap and table show the hierarchical data for your app’s size.

使用树状图

Using the treemap

树状图是数据结构的可视化表示。在视图中，空间被分解成矩形，其中每个矩形的体积和顺序由一些定量变量决定 (在本例中，体积以字节为单位)。每个矩形的面积与节点在编译后的应用程序中所占的大小成比例关系。在每个矩形（称为 A）的内部，还有更多的矩形存在于数据层次结构的更深层（A 的子级）。

A treemap is a visualization for hierarchical data. The space is broken up into rectangles, where each rectangle is sized and ordered by some quantitative variable (in this case, size in bytes). The area of each rectangle is proportional to the size the node occupies in the compiled application. Inside of each rectangle (call one A), there are additional rectangles that exist one level deeper in the data hierarchy (children of A).

要查看树状图中的单元格的详情，请选择这个单元格。这将重新确定树的根节点，以便选中的单元格作为树状图中新的根节点。

To drill into a cell in the treemap, select the cell. This re-roots the tree so that the selected cell becomes the visual root of the treemap.

如果要后退或向上导航，请使用树映射顶部的面包屑导航。

To navigate back, or up a level, use the breadcrumb navigator at the top of the treemap.

Screenshot of treemap breadcrumb navigator

支配树和调用图

Dominator tree and call graph

这个部分显示了代码的体积属性信息（例如：为什么编译后的应用程序中包含一段代码）。这些数据以支配树和调用图的形式呈现。

This section of the page shows code size attribution data (for example, why a piece of code is included in your compiled application). This data is visible in the form of a dominator tree as well as a call graph.

使用支配树

Using the dominator tree

支配树是一个树形结构的图表，其子节点可以立刻被支配。如果通往 b 的每条路径都必经节点 a，那么我们可以说：节点 a 支配了节点 b。

A dominator tree is a tree where each node’s children are those nodes it immediately dominates. A node a is said to “dominate” a node b if every path to b must go through a.

把它放在应用程序大小分析的上下文中，想象一下 package:a 导入了 package:b 和 package:c，并且 package:b 和 package:c 都导入了 package:d。

To put it in context of app size analysis, imagine package:a imports both package:b and package:c, and both package:b and package:c import package:d.

package:a
|__ package:b
|   |__ package:d
|__ package:c
    |__ package:d

在这个例子中，package:a 支配 package:d，所以这个支配树看起来像是这样：

In this example, package:a dominates package:d, so the dominator tree for this data would look like:

package:a
|__ package:b
|__ package:c
|__ package:d

这些信息对于您而言，可以帮助您理解编译后的应用程序中为何出现某些代码片段。例如，如果您正在分析应用程序的体积，并发现编译后的应用程序中包含意外的包，则可以使用支配树来跟踪包到其根源。

This information is helpful for understanding why certain pieces of code are present in your compiled application. For example, if you are analyzing your app size and find an unexpected package included in your compiled app, you can use the dominator tree to trace the package to its root source.

Screenshot of code size dominator tree

使用调用图

Using the call graph

调用图提供了与支配树相似的信息，帮助您理解编译后的应用程序中为何出现某些代码片段。它并不像支配树一样提供了一对多的代码体积数据节点，而是展示了代码体积数据的节点之间存在的多对多关系。

A call graph provides similar information to the dominator tree in regards to helping you understand why code exists in a compiled application. However, instead of showing the one-to-many dominant relationships between nodes of code size data like the dominator tree, the call graph shows the many-to-many relationships that existing between nodes of code size data.

我们再来看下面这个例子：

Again, using the following example:

package:a
|__ package:b
|   |__ package:d
|__ package:c
    |__ package:d

此数据的调用图会将直接调用者 package：b 和 package：c 与 package：d 链接到一起，而不是它的「支配者」 package：a。

The call graph for this data would link package:d to its direct callers, package:b and package:c, instead of its “dominator”, package:a.

package:a --> package:b -->
                              package:d
package:a --> package:c -->

这些信息对于理解代码片段（包、库、类和函数）之间的细粒度依赖关系非常有用。

This information is useful for understanding the fine-grained dependencies of between pieces of your code (packages, libraries, classes, functions).

Screenshot of code size call graph

我应该使用支配树还是调用图？

Should I use the dominator tree or the call graph?

如果您想理解应用程序中包含一段代码的根本原因，请使用支配树。如果您想理解一段代码之间的所有调用路径，请使用调用图。

Use the dominator tree if you want to understand the root cause for why a piece of code is included in your application. Use the call graph if you want to understand all the call paths to and from a piece of code.

支配树是调用图数据的分析或切片，其中节点是通过「支配」而不是父子层次结构连接。在父节点支配子节点的情况下，调用图和支配树中的关系是相同的，但情况并非总是如此。

A dominator tree is an analysis or slice of call graph data, where nodes are connected by “dominance” instead of parent-child hierarchy. In the case where a parent node dominates a child, the relationship in the call graph and the dominator tree would be identical, but this is not always the case.

在调用图完成的情况下（每对节点之间存在一条边），支配树将显示出 root 是图中每个节点的支配者。调用图可以让您更好地理解为什么在应用程序中包含一段代码。

In the scenario where the call graph is complete (an edge exists between every pair of nodes), the dominator tree would show the that root is the dominator for every node in the graph. This is an example where the call graph would give you a better understanding around why a piece of code is included in your application.

差异标签页

Diff tab

diff 标签页让您可以比较体积信息的两个快照。您要比较的两个体积信息文件应该从同一个应用程序的两个不同版本生成，例如，在更改代码之前和之后生成的体积文件。您可以使用树状图和表格可视化两个数据集之间的差异。

The diff tab allows you to compare two snapshots of size information. The two size information files you are comparing should be generated from two different versions of the same app; for example, the size file generated before and after changes to your code. You can visualize the difference between the two data sets using the treemap and table.

Screenshot of app size diff

读取体积文件

Loading size files

当您打开 Diff 标签页时，您将看到加载「旧」和「新」大小文件的使用说明。同样，这些文件需要从同一个应用程序生成。将这些文件拖放到各自的对话框中，然后单击 Analyze Diff。

When you open the Diff tab, you’ll see instructions to load “old” and “new” size files. Again, these files need to be generated from the same application. Drag and drop these files into their respective dialogs, and click Analyze Diff.

Screenshot of app size diff loading screen

查看生成体积文件可以得到有关生成这些文件的信息。

See Generating size files below for information on generating these files.

树状图和表格

Treemap and table

在差异视图中, 这个树状图和表格只会显示导入的两个文件中的差异数据。

In the diff view, the treemap and tree table show only data that differs between the two imported size files.

关于树状图的问题，可以查看使用树状图。

For questions about using the treemap, see Using the treemap above.

生成尺寸文件

Generating size files

要使用应用体积工具，您需要生成一个 flutter 体积分析文件。此文件包含整个应用程序的体积信息（本机代码、Dart 代码、资源和字体等），您可以使用 --analyze size 标志生成它：

To use the app size tool, you’ll need to generate a Flutter size analysis file. This file contains size information for your entire application (native code, Dart code, assets, fonts, etc.), and you can generate it using the --analyze-size flag:

flutter build <your target platform> --analyze-size

这会构建您的应用并输出尺寸的摘要到命令行，同时告诉您在哪里找到体积分析文件。

This builds your application, prints a size summary to the command line, and prints a line telling you where to find the size analysis file.

flutter build apk --analyze-size --target-platform=android-arm64
...
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
app-release.apk (total compressed)                               6 MB
...
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
A summary of your APK analysis can be found at: build/apk-code-size-analysis_01.json

在这个示例中，想要进行更进一步的分析，可以导入 build/apk-code-size-analysis_01.json 文件到体积分析工具。更多信息，可以查看应用体积尺寸文档。

In this example, import the build/apk-code-size-analysis_01.json file into the app size tool to analyze further. For more information, see App Size Documentation.

Flutter SDK overview

What’s in the Flutter SDK
flutter command-line tool
dart command-line tool

The Flutter SDK has the packages and command-line tools that you need to develop Flutter apps across platforms. To get the Flutter SDK, see Install.

What’s in the Flutter SDK

The following is available through the Flutter SDK:

Dart SDK
Heavily optimized, mobile-first 2D rendering engine with excellent support for text
Modern react-style framework
Rich set of widgets implementing Material Design and iOS styles
APIs for unit and integration tests
Interop and plugin APIs to connect to the system and 3rd-party SDKs
Headless test runner for running tests on Windows, Linux, and Mac
Dart DevTools for testing, debugging, and profiling your app
flutter and dart command-line tools for creating, building, testing, and compiling your apps

Note: For more information about the Flutter SDK, see its README file.

`flutter` command-line tool

The flutter CLI tool (flutter/bin/flutter) is how developers (or IDEs on behalf of developers) interact with Flutter.

`dart` command-line tool

The dart CLI tool is available with the Flutter SDK at flutter/bin/dart.

升级你的 Flutter 版本

升级 Flutter SDK
Upgrading the Flutter SDK
切换 Flutter 发布渠道
Switching Flutter channels
仅更新 packages
Upgrading packages
获得最新通知
Keeping informed

无论你使用哪个 Flutter 发布渠道，你都可以使用 flutter 命令来更新 Flutter SDK 和应用所依赖的 packages。

No matter which one of the Flutter release channels you follow, you can use the flutter command to upgrade your Flutter SDK or the packages that your app depends on.

升级 Flutter SDK

Upgrading the Flutter SDK

如果要升级 Flutter SDK 的话，请使用 flutter upgrade 命令：

To update the Flutter SDK use the flutter upgrade command:

$ flutter upgrade

这个命令首先获取你的 Flutter 渠道可用的最新的 Flutter SDK 版本。接着这个命令更新你 app 依赖的每一个 package，到最新的兼容版本。

This command gets the most recent version of the Flutter SDK that’s available on your current Flutter channel.

如果你想使用一个更加新的 Flutter SDK 版本，按照下面的步骤切换到相应的渠道 (channel)，接着再运行 flutter upgrade。

If you want an even more recent version of the Flutter SDK, switch to a less stable Flutter channel and then run flutter upgrade.

切换 Flutter 发布渠道

Switching Flutter channels

Flutter 有 4个发布渠道，分别是 stable, beta, dev, 和 master。我们推荐使用 stable 渠道除非你需要更加新的版本。

Flutter has four release channels: stable, beta, dev, and master. We recommend using the stable channel unless you need a more recent release.

要查看你当前使用的哪个渠道，使用下面的命令：

To view your current channel, use the following command:

$ flutter channel

要切换到其它渠道，使用 flutter channel <channel-name>。当你切换了渠道以后，使用 flutter upgrade 下载 Flutter SDK 和依赖的 packages。例如：

To change to another channel, use flutter channel <channel-name>. Once you’ve changed your channel, use flutter upgrade to download the Flutter SDK and dependent packages. For example:

$ flutter channel dev
$ flutter upgrade

仅更新 packages

Upgrading packages

如果你修改了 pubspec.yaml 文件，或者想仅更新项目依赖的 packages，而不是同时更新 packages 和 Flutter SDK，可以选择使用下面提到的 flutter pub 命令。

If you’ve modified your pubspec.yaml file, or you want to update only the packages that your app depends upon (instead of both the packages and Flutter itself), then use one of the flutter pub commands.

为了把 pubspec.yaml 文件里列出的所有依赖更新到 最新的兼容版本 ，可以使用使用 upgrade 命令：

To update to the latest compatible versions of all the dependencies listed in the pubspec.yaml file, use the upgrade command:

$ flutter pub upgrade

如果需要自动判断那些过时了的 package 依赖以及获取更新建议，现在你可以使用 outdated 命令。更多相关的信息，请参考 Dart 文档中关于 pub outdated 的说明。

To identify out-of-date package dependencies and get advice on how to update them, use the outdated command. For details, see the Dart pub outdated documentation.

$ flutter pub outdated

获得最新通知

Keeping informed

我们将在 Flutter 通知邮件列表上发布重大更改的公告。你也可以在 Flutter 开发邮件列表上提问！除了订阅接收公告外我们很乐意听取您的意见！

We publish breaking change announcements to the Flutter announcements mailing list. You can also ask questions on the Flutter dev mailing list. Aside from subscribing to receive announcements, we’d love to hear from you!

Flutter SDK 版本列表

Flutter 的 Stable channel 是相对稳定的发布版本，查阅这个文档了解更多：Flutter 的构建（发布）渠道 channels。

The Stable channel contains the most stable Flutter builds. See Flutter’s channels for details.